Customizing Application Master Pages – part 5 of 6

Introduction

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

1. Introduction to Master Pages.
2. Examining the out of the box Master Pages in SharePoint.
3. Developing a custom Master Page for SharePoint.
4. Deploy a Master Page for a production ready system.
5. Customizing the Application.master Page.
6. 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

1. Open Visual Studio
2. Create a New Project
3. 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)
4. Call it ApplicationHttpModule
5. Rename Class1 to ApplicationMasterModule
6. 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()
{
}
}
}

7. 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 “<New…>”
   • Enter a “Key file name”.
   • Uncheck the “Protect my key with a password” checkbox
   • Click “Ok”
8. Build the project
9. Place the dll in the GAC
   • If you built in Debug mode then the dll will be at: <project path>/bin/debug/ApplicationHttpModule.dll
   • Drag the dll (do not copy and paste) into the GAC: C:\Windows\assembly

Step 2 – Register the module

1. 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\<port>. 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.
2. Add this into the web.config file within the “httpModules” section

<add name=”CustomApplicationHttpModule” type=”ApplicationHttpModule.ApplicationMasterModule, ApplicationHttpModule, Version=1.0.0.0, Culture=neutral, PublicKeyToken=e04811459cf7ea00″ />

Note a few things:

• Type=<class name including namespace>, <name of assembly>
• 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.

1. Copy the application.master from %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS
2. Create a new folder called “MasterPages” under %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS
3. Paste the application.master page in the newly created MasterPages folder
4. 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.