SharePoint Magazine » page

Incorporating a Master Page into a SharePoint site definition

ggalipeau — Mon, 08 Dec 2008 14:35:37 +0000

Introduction

This is the sixth article in a six-part series on ASP.NET Master Pages and SharePoint.

Introduction to Master Pages.
Examining the out of the box Master Pages in SharePoint.
Developing a custom Master Page for SharePoint.
Deploy a Master Page for a production ready system.
Customizing the Application.master Page.
Incorporating a Master Page into a SharePoint site definition

In the previous article of this series we discussed how to build a customized master page and deploy it with a feature. However, the manual process of deploying the feature to each server in the farm and activating it isn’t as seamless as most developers would like. It would be nice to have the features automatically activate themselves when a new site in SharePoint is created from a template.

This article will discuss the creation of SharePoint site definitions, which are templates for SharePoint sites that will automatically create the master page feature on the site when created.

Site Definition

Site Definitions are templates that developers can build in SharePoint. You might also hear the term Site Template in SharePoint, which is a customization of a Site Definition. In order to clear up any confusion on these two terms, you can just think of them like this:

Site Definitions – SharePoint template that developers can create to manipulate how a site should be created. These are stored in the 12 hive of SharePoint and are referenced during site creation.

Site Templates – Customization of a Site Definition that administrators of the SharePoint site can create from the UI screens. These are stored in the content database and these are not meant for developers to manipulate.

When you create a SharePoint site and use one of the out of the box templates, you are actually using a Site Definition that Microsoft created and shipped with the SharePoint product. For more information about how SharePoint constructs the out of the box Site Definitions, please refer to the second article in this series: Examining the out of the box Master Pages in SharePoint .

WSP Solutions

In the fourth article of this series: Deploy a Master Page for a production ready system , we discussed the manual process of creating a feature, placing it in the 12 hive and deploying it with stsadm commands. While that is a valid process to deploy to SharePoint, it is a very manual process. Also, we are now bringing another factor into our project (i.e.: the Site Definition). So, we could manually deploy the site definition in addition to the feature, but now we are starting to have a lot of manual steps. Plus, if we have a large SharePoint farm, we are going to have to repeat these steps on each server.

Thus, SharePoint created a way to incorporate all your features, site definitions, etc… into one deployable solution. These solutions are called WSP files. WSP files are basically CAB files with an extension SharePoint understands so it can deploy to a SharePoint farm. These solutions automatically get deployed to all appropriate servers in the farm. Thus, you only have to install the WSP against the SharePoint web application in order to install all your features, site definitions, etc…

What are we showing in this article?

In this article we are going to show how to create a Feature, Site Definition and WSP solution.

The Feature will deploy the master page to the master page gallery of our site, just like in article four of this series: Deploy a Master Page for a production ready system.

The Site Definition will create the template for our site. This template tells SharePoint which aspx pages to create, which web zones to create, what features to activate, etc…

Lastly, the WSP solution will wrap everything up into one deployable package.

One question that undoubtedly comes up is “why are you incorporating the feature into the site definition instead of using feature stapling?” Feature stapling is the process of creating features and stapling them to Site Definitions that already exist. For example: let’s say you created a web part in a feature and you wanted that feature to be activated on all sites created with the WSS team site definition that comes out of the box in SharePoint. However, you want to keep all the other parts of that site definition intact, all you want to do is add one more feature onto it. With feature stapling you can create a feature and tell it to attach itself to pre-existing site definitions (even the ones that come out of the box in SharePoint).

The decision to use feature stapling versus custom site definitions has to deal with the amount of customizations you need to make. There might be times when you want to use feature stapling instead of brand new site definitions. However, in a lot of cases you need to make changes that go above and beyond just the features in a site definition. Thus, it is good to create custom site definitions to manipulate these functionalities. Plus, custom site definitions activate the features when the site collection is getting created, while feature stapling activates the features after the site has been created. This timing is important to understand in some complicated situations.

So, for this particular demo I am going to activate my master page feature in a custom site definition to show the process. But, I am not saying this is the best way. If you already have a site created and just need to deploy the master page feature, you might want to look into feature stapling as an option.

What tools are we going to use?

One of the more difficult things to understand when you first learn how to create WSP solutions is the install files that are needed to build the WSP solution. These files are called the manifest and the ddf files. These files basically explain to SharePoint what features, site definitions, etc… is part of your solution so that SharePoint can install the solution to the web application.

Since these files are difficult to understand, there are a lot of third party tools available that will build the manifest and ddf files for you. These tools are usually extensions to Visual Studio. Microsoft built one called Visual Studio Extensions for WSS. Plus, there are many open source ones on CodePlex including STSDEV, SPBuilder, WSPBuilder, etc… Each of these tools provides a different approach to building SharePoint solutions.

My personal favorite is WSPBuilder. The way this product works is it mimics the 12 hive in a Visual Studio solution. As long as your Visual Studio solution has the same folder structure as the 12 hive, it will build the correct files to create the WSP solution. This is very powerful and flexible. I like this over the Visual Studio Extensions for WSS because I feel that I am restricted in what I can do with Visual Studio Extensions for WSS.

The choice of the solution builder tools you want to use is a personal choice. For this article I am going to work with the WSPBuilder add-in for Visual Studio.

Here is an example of how WSPBuilder works. Notice that the servers 12 hive matches the Visual Studio solution:

Servers 12 hive

Visual Studio Solution

As long as the 12 hive matches, you can right click on your project and use the WSP Builder menu options to build your WSP file.

Also, when you are developing on a SharePoint server, you can right click on your project and use the WSPBuilder menu options to deploy your WSP file to the local server. This will deploy it to all web applications on your development machine.

Thus, when you are developing, you should be developing on a SharePoint server. Virtual machines such as VPC or VMWare are great for this. Then, every time you make a change you can just go to the deploy menu option of the WSPBuilder menu. After you are finished developing, you can build the WSP file using the menu options and it will physically place the WSP file in your projects folder. At this point you can copy that WSP file to the production machine and deploy it with stsadm commands.

Walkthrough

Create The Structure

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).

Scope=”Site” Version=”1.0.0.0″ Hidden=”FALSE” DefaultResourceFile=”core” xmlns=”http://schemas.microsoft.com/sharepoint/”
Description=”This Feature contains the demo master page”>

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:

MasterUrl=”~SiteCollection/_catalogs/masterpage/DemoCompany.master”>

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.

Customizing Application Master Pages – part 5 of 6

ggalipeau — Fri, 31 Oct 2008 10:17:41 +0000

Introduction

This is the fith article in a six-part series on ASP.NET Master Pages and SharePoint.

Introduction to Master Pages.
Examining the out of the box Master Pages in SharePoint.
Developing a custom Master Page for SharePoint.
Deploy a Master Page for a production ready system.
Customizing the Application.master Page.
Incorporating a Master Page into a SharePoint site definition

In this series we have discussed master pages and we have shown how to customize a master page. Before we finish up the process (i.e.: incorporating master pages into a SharePoint site definition), I would like to diverge and talk about a frustrating subject – application master pages. Customizing application master pages is a little different than other master pages within SharePoint. Thus, I wanted to break this out into its own article to describe the subtle complexities of them and why they exist.

What is the application master page?

The application master page is the master page for application pages (also called layout pages). Thus, to answer the question “what is the application master page?”, we will discuss what an application page is. In previous articles we discussed how SharePoint web pages are a mix of templates and content data from the database. This combination is merged behind the scene and the end user sees the page. This gives us the ability to create custom pages on the fly. However, there are some pages in SharePoint that are static and used across all web applications, site collections and sites. These pages are stored in the 12 hive and are not dynamically generated with content from the database (even though they might have webparts or user controls on them). These pages are usually used for setting or admin pages. A good example is the site setting page of your site. There is an easy way to tell if a page is an application page: it will contain the word “_layouts” in the url.

Most articles or posts on how to customize SharePoint web pages ignore the fact that these application pages exist. The reason is that the argument can be made that only adminstrators can access these pages. Well… that can be true in certain situations, but it is all about how the site is set up out of the box. If you don’t take the necessary steps to make sure that application pages don’t show up, then they will. A good example of this is the search page (I am talking about the site search page, not the Search Center). When you do a search in SharPoint and the search scope is set to the current site, then SharePoint will display the results on a search page that is an application page. Thus, the end user will see an application page in this instance. So, as you can see, it is important to customize the application master page unless you remove all references to all application pages that the end user of the system might see. This is very important if you are trying to customize an entire portal to change the look so it doesn’t look like a SharePoint site.

The out of the box application master page can be found at: %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS.

Microsoft’s recommendations for customizing application.master

According to this support site: http://support.microsoft.com/kb/944105 – there is two ways to modify/customize the application.master page.

Modify the application.master page in the 12 hive – Now… if you have been following this series of articles (or any other best practice article about SharePoint), then you will know you are NEVER suppose to modify files in the 12 hive. Other than the obvious issues this causes, including breaking the best practices Microsoft lays out, it also means we have to have the same application.master page for all web applications of a server. This means we can’t have two web applications on a server that have different look and feels.
Create a custom layouts folder – In my opinion this is a maintenance nightmare. You are copying your entire layouts folder to do this – not just the things that deal with application master pages. This seems like an extreme way to do something that I do not recommend.

For the reasons listed above, I don’t particularly agree with either of these recommendations.

Luckily others in the SharePoint community agree with my thoughts here and a common solution has been introduced throughout the SharePoint community. The solution is to implement custom HttpModules.

This approach is a non-supported approach, but the SharePoint framework leaves us little options. And, the “supported” approaches above seem to do more damage than good, so I can live with non-supported for now.

HTTP Modules

Http modules intercept page requests and allow custom code to run before the page actually renders. Thus, we can intercept the request and check if it is an application page. Then we can change the master page reference dynamically as the page renders.

Note: I originally learned the steps below from this blog by David Wise – http://www.sharepointblogs.com/dwise/archive/2007/01/08/one-master-to-rule-them-all-two-actually.aspx . I would like to thank David to allow me to use his steps in this article posting. David would also like to give credit to K. Scott Allen whom he originally got the dynamic replacement of master pages idea for regular asp.net applications.

Step 1 – build the project

Open Visual Studio
Create a New Project
Choose a Class Library project (for this walkthrough I am referring to a C# class library, but the steps are the same for other types)
Call it ApplicationHttpModule
Rename Class1 to ApplicationMasterModule
Change the code in ApplicaitonMasterModule to look like this:

using System;
using System.Web;
using System.Web.UI;
using System.IO;

namespace ApplicationHttpModule
{
public class ApplicationMasterModule: IHttpModule
{
public void Init(HttpApplication context)
{
context.PreRequestHandlerExecute += new EventHandler(context_PreRequestHandlerExecute);
}
void context_PreRequestHandlerExecute(object sender, EventArgs e)
{
Page page = HttpContext.Current.CurrentHandler as Page;
if (page != null)
{
page.PreInit += new EventHandler(page_PreInit);
}
}

void page_PreInit(object sender, EventArgs e)
{
Page page = sender as Page;
if (page != null)
{
if (page.MasterPageFile != null)
{
if (page.MasterPageFile.Contains(“application.master”))
{
page.MasterPageFile = “/_layouts/MasterPages/Custom.master”;
}
}
}
}

public void Dispose()
{
}
}
}

Sign the project – this is needed to add the dll to the GAC
- Right click on the ApplicationHttpModule project and go to the properties
- Go to the “Signing” link on the right side
- Click the checkbox to “Sign the assembly”
- In the “Choose a strong name key file” dropdown, choose “”
- Enter a “Key file name”.
- Uncheck the “Protect my key with a password” checkbox
- Click “Ok”
Build the project
Place the dll in the GAC
- If you built in Debug mode then the dll will be at: /bin/debug/ApplicationHttpModule.dll
- Drag the dll (do not copy and paste) into the GAC: C:\Windows\assembly

Step 2 – Register the module

Find the web config for your site. If you did not specify a path when you created your web application then this is located at C:\Inetpub\wwroot\wss\VirtualDirectories\. If you did specify a different path and don’t remember where it is, the best way to figure it out is to go into IIS, find your website, go to the properties, click on the “Home Directory” tab. Your path will be in the “Local path” text box.
Add this into the web.config file within the “httpModules” section

Note a few things:

Type=,
PublicKeyToken – this can be found by going to the dll in the GAC (C:\Windows\assmebly), then right click and look at the properties of the dll.

Step 3 – Put a custom master page in the layouts folder

In Step 1 we told the code to look for the master page in /_layouts/MasterPages/Custom.master. Thus, we need to actually have a master page there.

Copy the application.master from %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS
Create a new folder called “MasterPages” under %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS
Paste the application.master page in the newly created MasterPages folder
Rename the application.master page in the MasterPages folder to Custom.master

Step 4 – Make changes to the Custom.master

Now that you have built an HttpModule to redirect to the Custom.master page you can customize your Custom.master page however you want. But, you still have to be careful about keeping the content place holders around per the articles I have been writing in this series.

Be Careful

Just like the regular SharePoint master pages you must still be careful when you start modifying application master pages. Here are a couple of things to make sure you do:

Don’t remove content place holders. The pages that implement the application master page assume these content place holders are there. So, any content place holder from application.master must be in your custom application master page. If you are sure you have a content place holder that is not needed, then don’t remove it – just wrap it in a tag and turn the visible property to false.
You can’t have a search control on the application master pages. I am not sure of the reason for this, but you can’t have the out of the box search control on the application master pages.
Some of the application pages are actually formatted incorrectly. Thus, when you build a custom application master page you could inadvertently mess up an out of the box application page. This can happen even if your application master page is formatted perfectly. Please read my blog post on this subject for more information: http://greggalipeau.wordpress.com/2008/07/30/custom-applicationmaster-working-around-microsoft-bugs/
Do not use this method if your install has the SSP on the same server as the main SharePoint application. There has been reported issues of the SSP having issues with this approach because the system master pages they use have a different setup.

Conclusion

This is not as much of a conclusion, as it is a plea to the developers at Microsoft who are creating the next version of SharePoint. Please make sure we have a clear path to change application master pages. Hopefully the highly anticipated 14 hive will help with the current situation.

Deploying the Master Page (Master Pages and SharePoint part 4 of 6)

ggalipeau — Fri, 24 Oct 2008 07:20:53 +0000

Introduction

This is the fourth article in a six-part series on ASP.NET Master Pages and SharePoint.

Introduction to Master Pages.
Examining the out of the box Master Pages in SharePoint.
Developing a custom Master Page for SharePoint.
Deploy a Master Page for a production ready system.
Customizing the Application.master Page.
Incorporating a Master Page into a SharePoint site definition

In the previous article of this series we discussed how to build a customized master page in SharePoint Designer. At the end of the previous article we discussed that making the modifications directly in SharePoint Designer is not the most deployable solution for production life cycle environments.

This article will discuss the other option to customize and deploy a master page for a production ready system.

Features

Features are SharePoint’s way to activate and deactivate certain code on particular site and/or site collection, within a SharePoint website. Features can contain things like – what webparts should be available, what lists should be available, what actions should be on list menus, etc…

Features can also deploy master pages to the master page gallery of a SharePoint site and/or site collection. Using a feature to deploy the master pages gives us reusable files that can be deployed to any SharePoint environment through SharePoint commands. This means that we can create build scripts to deploy our master page to a master page gallery. This is much better than the copy and paste method of SharePoint Designer we showed in the previous article.

Features contain two main files:

Feature.xml -When a feature is installed SharePoint looks for the feature.xml file to determine how to deploy the feature. The feature.xml file defines the feature and provides the paths to the other files involved in deploying the feature.
Elements Manifest – this file is referred to from the feature.xml. This is the file that determines what the feature should do when it is activated.

Features can be installed to a SharePoint environment through stsadm commands. Stsadm is the command line tool for SharePoint and is used for multiple administrative and development operations in SharePoint.

Once a feature is installed on a SharePoint machine, it can be activate or deactivated on a particular SharePoint site or site collection. Every feature.xml file contains a “Scope” attribute. If the scope of a feature is “Web”, that means that the feature can only be activated at the SharePoint site level. If the scope of a feature is “Site”, that means the feature can only be activated at the SharePoint site collection level. Site Collections contain all the sites in a SharePoint tree, thus if a feature is activated at a site collection, it is activated for all the sites in the site collection. If a feature is activated at a site, it is activated for that site only.

To activate a feature you can go to a site and/or site collection and then go to the Site Settings. In the site settings you will see a link for “Site features”. If you are on a top level site in the site collection, you will also see a link for “Site collection features”.

When you click on the “Site features” and/or “Site collection features” link you will go to the feature activation page for the site and/or site collection respectively. From this page you can activate or deactivate sites for the site and/or site collection.

Custom Master Page file

To customize a SharePoint master page with a feature, you need to create a custom master page file. This file gets uploaded to the master page gallery in SharePoint through the feature.

There are multiple ways to create your own master page files. Here are a few techniques I recommend:

Copy Technique:
- Copy the default.master from %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\Global.
- Make your changes directly to the html (in the copied file).
- Make sure the copy file has a different name than default.master.
Designer Technique
- Make your changes in SharePoint designer as described in the previous article: http://sharepointmagazine.net/technical/customisation/developing-a-custom-master-page-master-pages-and-sharepoint-part-3-of-6.
- Do not save these changes against your site – you can do this against a test site to make things easier.
- Copy the html out into a custom master file and give it a unique name.
Minimal Master technique
- Make a master page file with the minimal master html code found here: http://msdn.microsoft.com/en-us/library/aa660698.aspx
- The minimal master html is a master page with all the content place holders that you will need for SharePoint. This is a good starting point if you want to start from scratch in creating your master page. You should become familiar with what all the content place holders are for when using this technique.
- Save this file as a new master file and give it a unique name.

Create the Feature

Features are created in Visual Studio and then moved into the SharePoint 12 hive %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES. After the feature is in the 12 hive, stsadm commands can be used to deploy the feature to the SharePoint environment. Then the feature needs to be activated on the SharePoint site.

Steps to create a feature for Master Page deployment:

Note: We will not be using any tools like Visual Studio Extensions for WSS or WSPBuilder for this walkthrough. However, I recommend using these tools to wrap the features in solutions. We will talk more about this in the last article in this series.

Open Visual Studio
Create a New Project
Choose a Class Library project (for this walkthrough I am referring to a C# class library, but the steps are the same for other types)
Call it DemoMasterPageFeature
Delete Class1.cs
Add a new folder to the project and call the folder “12″
Add a new folder to the “12″ folder, call it “Template”
Add a new folder to the “Template” folder, call it “Features”
Add a new folder to the “Features” folder, call it “DemoMasterPage”
Add a new folder to the “DemoMasterPage” folder, call it “MasterPages”
Add a new master page file to the MasterPages folder
- There are multiple ways to create this file
  - You can copy the one from SharePoint
  - You can copy a modified one out of SharePoint Designer. If you have been following this series you can go to article 3 {insert link here} and use the html we modified in SharePoint Designer for your new master page file.
  - You can start with a minimal master page http://msdn.microsoft.com/en-us/library/aa660698.aspx
- We are going to use the technique of copying the one from SharePoint
  - Go to %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\Global.
  - Copy the default.master
  - Paste it in the MasterPages folder (in the Visual Studio project)
- Rename the file demomasterpage.master
Add a feature.xml file to the DemoMasterPage folder.
- This file tells SharePoint how to install the master page
- It must be called “feature.xml”
- Put the following xml in it
Scope=”Site” Version=”1.0.0.0″ Hidden=”FALSE” DefaultResourceFile=”core” xmlns=http://schemas.microsoft.com/sharepoint/ Description=”This Feature contains the demo master page”>
- Notice the following:
  - Scope – this tells SharePoint where to install the feature. Our scope is “site”, thus we want to install the feature at the site collection level. This is because our master page gallery lives at the site collection level. If we wanted to install the feature at the sub-web level, it would say “web”
  - ElementManifest – this tells SharePoint the other files involved in creating this feature. Remember, SharePoint only knows to look at the feature.xml file when installing a feature, so the feature.xml file must tell SharePoint about the other files involved.
  - Id – this is the unique GUID for the feature. It must be unique. So, if you create multiple features, make sure you use a unique GUID here. This is also how we can reference the feature when we start building solutions.
Add an elements.xml file to the DemoMasterPage folder
- This file tells SharePoint what to do with this feature. For example: we want to deploy our master page to the master page gallery. This is the file that will tell SharePoint to do that.
- It doesn’t have to be called elements.xml. But, it does have to be called whatever you put as the ElementManifest Location in the feature.xml file. I like to use elements.xml when I create these files
- Put the following xml in it
- Notice the following:
  - Url – this is how we tell SharePoint to put the file in the master page gallery. _catalogs/masterpage is the location of the master page gallery when dealing with site collections. We know we are dealing with site collections because the feature.xml file has a scope of “site”.
  - File – this tells SharePoint the name of the file it is going to put at the master page gallery. The type is “GhostableInLibrary” – this means the file is still going to be on the 12 hive and SharePoint is going to keep a Ghosted reference to the file. Please refer to article 3 http://sharepointmagazine.net/technical/customisation/developing-a-custom-master-page-master-pages-and-sharepoint-part-3-of-6 for more information about Ghosting.
Build the project in order to save your changes.

The final folder/file structure should look like this:

Deploying the Feature

There are 2 steps to deploy a feature:

Copy the contents to the 12 hive.
- Copy the folder “DemoMasterPage” (this is the folder we created in the Visual Studio solution in the last section). Be careful to only copy the “DemoMasterPage” folder, not all the folders we created.
- Paste the “DemoMasterPage” folder in %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES.
Run stsadm commands to install the feature
- Open up a command prompt
- Enter the following: cd C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN.
  Note: this assumes you installed SharePoint on your C drive. Please change the install path if otherwise.
- Enter the following: stsadm -o installfeature -name DemoMasterPage -force
  Note: do not copy and paste. Sometimes copy and paste into command lines won’t work. Please retype in your command line
- Enter the following: stsadm -o activatefeature -name DemoMasterPage -url http://mysitecollectionpath -force
  Note: do not copy and paste. Sometimes copy and paste into command lines won’t work. Please retype in your command line
  - The string after “name” is the name of feature of your feature folder.
  - The url is the url to your site collection root. You can copy it from your browser, but don’t keep the “default.aspx” on the path

What’s wrong with this picture?

Any developer will say this is not correct. Developers don’t want to copy files manually and paste them in a folder. Yes, I understand this. I am showing this technique to lead up to the last article in this series on solution deployment. The solution will take care of moving the files to the 12 hive and running the commands for you. However, it is important to understand what solutions do before jumping right into them. Thus, I am showing you this manual way so you can get an idea of what the solution is doing behind the scenes.

Set the new master page

The feature we just created placed the new master page in the master page gallery. However, it did not tell SharePoint to use this new master page on your SharePoint site. There are multiple ways to do this including: custom site definitions, programmatically setting the default master page, using SharePoint Designer, or using the MOSS master page selection page.

If you are using WSS, please refer to article 3 in this series http://sharepointmagazine.net/technical/customisation/developing-a-custom-master-page-master-pages-and-sharepoint-part-3-of-6 in order to see how to set the master page in SharePoint designer.

If you are using MOSS, you can go to your site collection and then go to site settings. Then under “Look and Feel” click on the “Master Page” link. You can now choose the demomasterpage.master to be the master page for your site collection.

Please Note: This assumes you have the Publishing feature turned on in MOSS. The Publishing feature might be turned on and might not be turned on based on the site definition you used to create your site. If the Publishing feature is not turned on in MOSS you will not see the “Master Page” link under “Look and Feel” in the Site Settings page. To turn the Publishing feature on go to Site Settings, then look under the “Site Collection Administration” column and then click the “Site collection features” link. Find the “Office SharePoint Server Publishing Infrastructure” column and click Activate. Now, when you go back to the Site Settings – “Look and Feel” column you will see the “Master Page” link.

Making Changes to the Master Page

Now the Master Page has been installed to the SharePoint farm and activated on the site collection. So, what if you want to make further customizations to the master page? Do you have to go through the process of re-installing and re-activating? The answer is no. Here comes the power of ghosting. Please refer to article 3 http://sharepointmagazine.net/technical/customisation/developing-a-custom-master-page-master-pages-and-sharepoint-part-3-of-6 for more information about Ghosting. Since the master page is ghosted, the SharePoint site keeps a reference to the 12 hive version of it. So, if you want to make a change to your master page, all you have to do is update the demomasterpage.master file in the feature folder of the 12 hive (%Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEA)TURES.

Deactivating the Feature

Sometimes there are changes you need to make to a feature that are not ghosted. Examples of these types of changes are things in the feature.xml file. You cannot change the id of a feature.xml file and expect to be able to just re-install and re-activate the feature. Instead, you have to deactivate the feature and uninstall the feature first. Here are the commands to do this.

Open up a command prompt
Enter the following: cd C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN.
Note: this assumes you installed SharePoint on your C drive. Please change the install path if otherwise.
Enter the following: stsadm -o deactivatefeature -name DemoMasterPage -url http://mysitecollecitonpath -force
Note: do not copy and paste. Sometimes copy and paste into command lines won’t work. Please retype in your command line
Enter the following: stsadm -o uninstallfeature -name DemoMasterPage -force
Note: do not copy and paste. Sometimes copy and paste into command lines won’t work. Please retype in your command line

Conclusion

Using features to deploy the master page to the master page gallery is a reusable way to deploy master pages in SharePoint. However, there are still manual processes involved (including copying files to the 12 hive). Thus, using features is not the complete story when dealing with SharePoint deployments. In the last article in this series we will discuss SharePoint solutions (WSPs). WSPs are basically CAB files that wrap up features in SharePoint for easy deployment. The WSP file will move the feature files to the 12 hive for you. However, I think it is important to understand how this is done before jumping into creating WSP solutions. Plus, we can reuse the feature we created in this article when we build the WSP solution out in the final article of this series.

Developing a Custom Master Page (Master Pages and SharePoint part 3 of 6)

ggalipeau — Mon, 06 Oct 2008 10:30:55 +0000

Introduction

This is the third article in a six-part series on ASP.NET Master Pages and SharePoint.

Introduction to Master Pages.
Examining the out of the box Master Pages in SharePoint.
Developing a custom Master Page for SharePoint.
Options to deploy a Master Page for a production ready system.
Customizing the Application.master Page.
Incorporating a Master Page into a SharePoint site definition

In the previous two articles of this series we discussed master pages and how SharePoint uses them to create it’s out of the box pages. Now that we have an understanding of how master pages work and how SharePoint uses them, we can start showing how to develop custom master pages.

There are two supported scenarios for customizing master pages in SharePoint:

Edit the master page in SharePoint Designer
Create a custom master page and upload it to the master page gallery

Please notice that modifying the existing master page file is not one of the supported options. Microsoft rarely supports changing files in SharePoint unless it is done from SharePoint Designer.

In this article we are going to concentrate on the “Edit the master page in SharePoint Designer” option. This will show us how to develop a custom master page. In the next article we will learn how to deploy this custom master page for a production ready system.

UnGhosting (Customizing)

When a new site in SharePoint is created it uses the default.master for its master page, which is located at %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\Global.

Note: This is true for WSS team sites and standard MOSS team sites (MOSS publishing sites might use a different master page to start with).

SharePoint keeps a reference to this one file no matter how many sites are created. This is a process called Ghosting, or Uncustomized. Thus, every site collection and/or site in SharePoint point to one file.

If a master page is customized in SharePoint Designer, SharePoint stores a modified version of the master page in the content database (this is a technique called “Unghosting” or “Customizing”). This process basically breaks the reference SharePoint keeps to the default.master file on the 12 hive. The reason for this is that changes will not affect the other content pages that refer to it.

SharePoint Designer can’t modify the default.master page in the 12 hive because it would modify a file that multiple site collections and/or sites use. Instead, it goes through the “UnGhosting”, or “Customizing”, process. This is the process of removing the link to the 12 hive and making a copy of the default.master in the content database.

SharePoint Designer

SharePoint Designer knows about the SharePoint architecture. Since the SharePoint architecture is a mixture of physical files (on the 12 hive) and content (from the database), a web design tool for SharePoint must know about this architecture. SharePoint Designer is the only tool currently available that knows about this architecture. SharePoint Designer knows how to render the structure of the SharePoint site and how to allow for changes using the UnGhosting, or Customizing, techniques.

To modify a master page in SharePoint Designer first open SharePoint Designer on your SharePoint box. Next open the SharePoint site by going to File – Open Site. In the Site Name field put the url to the home page of your SharePoint site, without the actual page in it (i.e.: don’t keep default.aspx in the string).

After you open a site in SharePoint Designer, Designer will create the folder structure for the SharePoint site:

Create a new master page

The master page gallery is located in the _catalogs folder. Within the master page gallery you will find the default.master page. You can modify this file directly, but it is good practice to make a copy of this file and modify the copied file. I am going to call this copied master page “customDefault.master”.

After you make a copy of the master page, the content pages will not know that this is the master page they should use. So, default.aspx is the content page. And if you open default.aspx in SharePoint Designer, you will notice this in the upper right corner:

Notice that it is still pointing to the default.master page. If you want it to point to the new customDefault.master page, then right click on customDefault.master (in the Folder List) and choose “Set as Default Master Page”. After doing this, open the default.aspx page again and notice that the master page referenced changed:

So, why does this reference pointer change, but the MasterPageFile still points to default.master (MasterPageFile=”~masterurl/default.master”). The reason is dynamic tokens. SharePoint replaces “masterurl/default.master” with the dynamic token value at run time. The reference pointer we are seeing is that dynamic token. So, when you click “Set as Default Master Page” in SharePoint Designer, you are changing the dynamic token for the SharePoint site. For more information on dynamic tokens, refer to the second article in this series – Examining SharePoint Master Pages.

Customize the customDefault.master

Open up the new customDefault.master page. If you are using MOSS, SharePoint Designer might ask you to check it out at this point. If you are in WSS, you shouldn’t have to check the file out.

SharePoint Designer has three different modes for customization:

Design – WYSIWYG editor
Code – html editor
Split – keeps the design and code modes open

I prefer to keep SharePoint Designer in split or code mode. The reason is that when you customize a SharePoint master page you have to be careful where you put customizations. If you place a customization in a ContentPlaceHolder, there is a chance the customization won’t show on the final page because the implementing content page might take care of filling in the particular ContentPlaceHolder. So, if you make changes in design mode, it is beneficial to see what is happening in the html.

So, let’s make some customizations so you can see some things that can be done.

Create a footer

Find the tag in your code view and put your cursor right before it.
Type the some footer text – ex: Copywrite RDA all rights reserved 2008.
Wrap the footer text in a div tag.
Set a class to the div tag. For example purposes we can use an out of the box css class from SharePoint

Save the file.

Note: SharePoint Designer should give you a popup telling you that you are about to UnGhost, or Customize, your SharePoint master page. This is your warning that you are going to break that reference to the 12 hive and make a separate master page in the content database. Click Yes.

Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
Open your site in your web browser to see the change.

Create a new style

Our footer example uses the out of the box “ms-CommentFooter” for our css class. This example will show you how to change that to one of your own custom css classes.

Change “ms-CommentFooter” to “custom-footer” in the code view

Select the “new style” link from the Apply Styles toolbar on the right

Set the properties of the style
- Selector = .custom-footer
- Font
  - Font-family = Verdana
  - Font-size = x-small
  - Font-style = italic
Click Ok on the style popup
Save the file
Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
Open your site in a web browser to see the changes

Modify a SharePoint Control

Find the top menu in the code view

ID=”TopNavigationMenu”sdgds
…

Change the Orientation to Vertical

Orientation=”Vertical”

Save the file
Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
Open your site in a web browser to see the changes. Your menu control should be vertical now.

(Please not the intent of the above change is to show that the out of the box SharePoint controls can be changed. I understand that the actual change we made is not user friendly).

Modify out of the box css classes

Find the text “ms-globalbreadcrumb” in the code.
Right click on it.
Click “Follow Code Hyperlink”
- a. It will take you to one of the sections for this css class
- b. The section right above it contains the code for the background color.
- c. Change the background color to #000000

.ms-globalbreadcrumb{
font-size:8pt;
text-align:right;
background-color:#000000;
padding:2px 10px 2px 5px;
}

Save the css file

Note: SharePoint Designer should give you a popup telling you that you are about to UnGhost, or Customize, your css file. This is your warning that you are going to break that reference to the 12 hive and make a separate css file in the content database. Click Yes.

Open your site in a web browser to see the changes. The top bar should be black now.

(Please not the intent of the above change is to show that the out of the box SharePoint controls can be changed. I understand that the actual change we made is not user friendly).

Be careful with your power

These are just a few examples of some customizations that can be done to the master page through SharePoint Designer. The customizations you can do are endless. However, you must be careful that you do not customize something that is required for SharePoint to work.

Some examples of controls you don’t want to remove are:

Site Actions
Search (if you want search capabilities)
Navigation menus (unless you want to replace them with your own navigation)
Etc…

Also, be careful where you make your changes. In the previous articles we talked about how making changes to content within ContentPlaceHolders might get overridden by the implementing content page. Thus, if you make a change to a ContentPlaceHolder, you might not see it on your page. My recommendation is to put SharePoint Designer into Split mode or Code mode so you can edit the html directly and you can be sure that you are not editing html within ContentPlaceHolders.

And remember; don’t remove any of the ContentPlaceHolders. The content pages in SharePoint already have references to these place holders. If you remove them the content pages might break.

Undo your Customizations

After making the change notice the default.master in the folder list on the left side. It now has a symbol next to it. If you mouse over that symbol it will tell you that the page has been customized. This is telling you that you have UnGhost, or Customized, this page at one point.

If you decide that you made a mistake by UnGhosting, or Customizing, your file – then you can undo your changes by “re-Ghosting” the file. To do this, right-click on the default.master file and choose “Reset to Site Definition”.

SharePoint Designer Pros

Easy – SharePoint designer provides an easy experience to customize SharePoint master pages. Any user with html experience should be able to use SharePoint designer to make changes to a master page. As the steps above show – you can just open your master page up, make your changes and then save your changes in SharePoint Designer.

UI experience – SharePoint designer gives you a WYSIWYG (what you see is what you get) UI experience. This means you can make changes to the website through an interface that looks like the website. The other techniques we are going to mention do not allow for this.

SharePoint Designer Cons

Unghosting/Customizing – the Unghosting, or Customizing, technique keeps all changes scoped to the respective site collection. There is no real way to point the master page to another site collection. This can hurt maintainability if you are creating multiple site collections on one SharePoint box and want to keep a consistent master page.

Not Deployable – SharePoint Designer forces you to make changes directly against a SharePoint site collection. This makes it hard to move from a development, to QA, to production environment. This also makes it so the customized master page cannot be used against multiple site collections.

Conclusion

SharePoint Designer provides us a quick way to customize master pages in SharePoint. This is a great tool to design master pages and/or customize an existing SharePoint site. However, SharePoint Designer does not provide a clear deployment path for projects using a development lifecycle. The next article in this series will show how to create custom master pages that can be uploaded to any SharePoint site for easy deployments.

Examining the out of the box Master Pages in SharePoint

ggalipeau — Mon, 15 Sep 2008 11:18:30 +0000

Introduction

This is the second article in a six-part series on ASP.NET Master Pages and SharePoint.

Introduction to Master Pages.
Examining the out of the box Master Pages in SharePoint.
Developing a custom Master Page for SharePoint.
Options to deploy a Master Page for a production ready system.
Customizing the Application.master Page.
Incorporating a Master Page into a SharePoint site definition

Previously in Introduction to Master Pages we discussed master pages in relation to general ASP.NET. Now that we have a generally understanding of how master pages work, we can discuss how SharePoint has implemented them. This article will discuss the out of the box master pages in SharePoint in order to gain an understanding of how SharePoint customized the out of the box site. These same techniques will be used to build our own, customized SharePoint sites.

Master Page Gallery

In the previous article we described master pages and content pages. Content pages contain a reference to the master page to determine the place holders to fill in. In an ASP.NET application the master page can live on the file system so a direct reference can be made to a physical file on the system. This same concept is possible in SharePoint; however that wouldn’t take advantage of the natural SharePoint structure.

SharePoint is based on lists/libraries. These are galleries in which multiple instances of particular information can be added. The basic example of these is the document library. You can upload multiple documents, edit individual documents, change metadata about documents, etc… Lists/libraries give SharePoint users access to information directly in the comfortable SharePoint webpage. The advantages of this are that if you need to add a new item to a list/library you don’t have to ask a developer to do it (like a typical ASP.NET application).

SharePoint master pages have their own list/library called the Master Page Gallery. This is a location on the site where a site administrator can access and modify SharePoint master pages. To access a SharePoint master page gallery go to a SharePoint site collection, go to the Site Settings, then click on the master page gallery.

The advantage of storing master pages in the SharePoint master page gallery is that you have easy access to the master pages (even after the site has been deployed). You can make your changes to the master page and then upload it to the master page gallery when you are finished. If your content page already points to that master page, the end user will see your master page changes as soon as the newly edited master page is checked in.

SharePoint Site Structure

SharePoint is built on a template structure. These templates are referred to as Site Definitions. You might also hear the term Site Template, however that is a customization of a site definition – thus it is still built on the same principles.

Site definitions contain the pages you see on the SharePoint site with sections that can be modified. A good example of this is when you choose to create a team site in SharePoint.

When you choose to create a team site you are choosing to create a site based off the team site definition. This site definition determines the pages that show in the site (for example: the default.aspx page) and the initial content to fill the site in with.

The page that gets created in the site definition (for example: default.aspx), is a content page. In the first part of this series (Introduction to Master Pages) we discussed how content pages refer to a master page. Thus, the out of the box content pages, within the SharePoint site definitions, have references to the master pages in the master page gallery.

Dynamic Tokens

Previously I mentioned that the SharePoint content pages refer to master pages from the SharePoint gallery. This would lead one to assume that there is a hard coded path, to the master page, from the content page.

However, if this is a hard coded path to the master page, then it can never be changed without modifying the actual content page. But, SharePoint provides a way for the administrator of a site to switch the master page through the UI.

This is a MOSS publishing feature, which is not available on WSS or a standard MOSS site. However the underlying architecture is the same in every version (they just didn’t give the user the ability to see this screen in WSS and standard MOSS).

So, how does SharePoint accomplish this architecture? SharePoint has a master page token replacement functionality that runs when you view a site.

There are 3 tokens available for SharePoint master page references:

Dynamic Token – ~masterurl/default.master
Dynamic Token – ~masterurl/custom.master
Static Token – ~site/mymaster.master and ~sitecollection/mymaster.master

So, what is the difference between dynamic tokens and static tokens?

Static Token – direct reference to a master page. If your aspx page is at http://mysitecollname/mysitename/default.aspx and your static token is ~sitecollection/mymaster.master, then your master page file has to live at http://mysitecollname/mymaster.master. Or, if you static token is ~site/mymaster.master then your master page has to live at http://mysitecollname/myysitename/mymaster.master.

Dynamic Token – replacement reference to a master page. This means that SharePoint will replace this string with the real reference to the master page when the screen renders. Basically there are two settings for every site called MasterURL and CustomMasterURL. MasterURL maps to “System Master Page” in the screenshot above. And, CustomMasterURL maps to “Site Master Page” in the screenshot above. If SharePoint sees ~masterurl/default.master in your content page, then it replaces it with whatever is in the MasterURL property. If SharePoint sees ~masterurl/custom.master in your content page, then it replaces it with whatever is in the CustomMasterUrl property.

The Dynamic Token architecture allows SharePoint to replace the master page reference at run time. Thus, SharePoint has the flexibility of providing UI screens for the end users to replace the master pages (even though they only provide this UI on MOSS publishing pages). This functionality is also available through code for any version of SharePoint. So, developers can do this programmatically if necessary too.

Example from SharePoint’s team site definition:

<%@ Page language=”C#” MasterPageFile=”~masterurl/default.master” Inherits=”Microsoft.SharePoint.WebPartPages.WebPartPage,Microsoft.SharePoint,…

Type of Master Pages

There are 3 main types of Master Pages in SharePoint:

Site Master Pages
System Master Pages
Application Master Pages

Site master pages are usually used in SharePoint publishing site definitions, but they can be used for any SharePoint version. These pages are used so the main page can have one master page while the subpages and views use other master pages (example of a subpage is a view of a list or library). This is needed for publishing pages because the main page, of a site or subsite, usually has the publishing feature turned on while the other pages don’t. These publishing UI functionalities are contained in the master page, thus you need a separation of master pages between the main page and the subpages.

This technique is not specific to publishing pages. A good example of this is the meeting workspace site in MOSS. This site definition is not a publishing site. However the main page is different than the subpages. This is accomplished by making the main page a site master page.

Site master pages are defined by ~masterurl/custom.master in the content page declaration.

System master pages are used for most non-publishing sites and subpages in publishing sites. The system master page is what you typically see when you go to a WSS site or a non-publishing MOSS site.

System master pages are defined by ~masterurl/default.master in the content page declaration.

Application master pages are for all “Layout” pages. Layout pages are SharePoint administrative pages that are typically seen when doing site administration. You can tell a layout page because the URL of the site has _layout in it. Layout pages are static, file server pages that are not driven by the database like other pages in SharePoint. We will discuss application pages in more detail in article 5 of this series because of the difficulties involved in understanding and customizing them.

Application master pages can be found at: %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS.

Examining the Default.master

In order to get an understanding of how SharePoint implements its master pages, we are going to examine the default.master page. This is the master page used for the typical “out of the box” SharePoint site. The default.master can be found at %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\GLOBAL. When a new SharePoint site is created, this master page is moved from this 12 hive path to the master page gallery of the newly created site. Actually, “moved” is not the appropriate word. In fact, SharePoint just keeps a reference in the master page gallery to the file on the 12 hive path. This is a concept called Ghosting or Un-customizing.

Now that we understand how SharePoint deals with the default.master page, we can look at what the default.master page contains. This master page contains what any other master page would contain – html and ContentPlaceHolders.

The html in the default.master contains things such as:

ASP.NET menu control – for navigation (top)
Site Actions html – for editing the page
Design mode area – for exiting out of edit mode
Search controls
Quick Launch area – for navigation (left side)
Etc…

All of the out of the box pages in SharePoint, know how to deal with the ContentPlaceHolders from the default.master page. That is a hint for anyone thinking about how they can customize master pages – you want to use the same ContentPlaceHolders that the default.master contains.

Master pages for publishing sites

The publishing site is a MOSS feature that allows the SharePoint site to act more like an Extranet or Internet (rather than just an Intranet). While a publishing site is not needed to create an Extranet or Intranet, it provides a lot of functionality to make the process easier. One of these functionalities is the ability to switch the master page from the UI.

Another one of these functionalities is that SharePoint provides more master pages in the master page gallery. These are out of the box master pages that make a SharePoint site look more customized.

This is customization tip #1: for a quick way to make a SharePoint site look “less like SharePoint” create your site as a publishing site and pick one of the “extra” master pages provided for publishing sites.

The out of the box master pages for publishing sites can be found at %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\PublishingLayouts\MasterPages. Just like the default.master, these master pages are moved to the master page gallery of the SharePoint site when the publishing site is created. Once again, just like default.master, the word “moved” is actually incorrect because SharePoint technically keeps a reference to the master page on the 12 hive file system (the concept called Ghosting or Un-Customizing).

Actually, these get moved to the master page gallery when the publishing feature of the SharePoint site is activated. But, the publishing feature is activated when a publishing site is created, so it is appropriate to say the publishing master pages get moved to the master page gallery when a publishing site is created.

Theory behind creating Custom Master Pages

You might think that you can just modify the default.master from the 12 hive, or one of the publishing master pages, in order to customize a SharePoint master page. However, this is not recommended best practice. The reason for this is Microsoft could put out a patch for SharePoint that replaces the out of the box master pages, thus overwriting your changes.

However, you can modify the master pages by going to SharePoint designer and making your customizations there. You might ask “why can I do this in SharePoint designer and not to the file directly”? The reason is SharePoint designer UnGhosts or Customizes a page. Unghosting, or customizing, is the process SharePoint takes to break the reference to the physical file and makes a virtual copy of that file for you to use directly within your SharePoint site. This is good practice for quick changes. However, this forces you to code directly against a site, rather than wrapping it up in a good solution (which should be done for development efforts in order to keep things deployable).

Thus, if you are not in a situation where you can make a change to the master page directly against the site (i.e.: SharePoint Designer), then the process for customizing master pages is to create your own master page and upload it to the master page gallery. Then re-point the master page reference on the SharePoint page to your new master page. This concept will be demonstrated in the following articles in this series.