donderdag 6 november 2008

Using a centrally manageable custom masterpage

The standard microsoft way of deploying a custom masterpage is by making a custom provisioning feature that deploys your masterpage and all of its assets to the _catalogs/masterpages folder of your site collection.

Imagine if at the moment of deployment there is no certainty on how the masterpage will be in a certain amount of time and it is bound to change.

Are you going to manually deactivate and reactivate all these features or should there be another way?

Today I'm going to show you another way to centrally manage your masterpage so you only have to adjust it on one place.. you guessed it right: the layouts folder!

If you try to change one of the 4 masterpage tokens ( ~masterurl/default.master ; ~masterurl/custom.master ; ~site/custom.master ; ~sitecollection/custom.master) to a masterpage located in your layouts directory you get an error (the referenced file is not allowed on this page) telling you that this is an unsupported attribute.
Now how will we solve this issue? We will create a httpModule that will replace the masterpageurl in the pre-init event of the loaded page.

Step 1:
Copy your masterpage in your layouts folder (12/Template/Layouts/MyProject)

Step 2:
Create MasterPageModule.cs
> Let this class inherit from System.Web.IHttpModule
> Implement the Init() and Dispose()


public class MasterPageModule : 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 (SPContext.Current.Web.WebTemplateId == 10001)
if (page != null)
if(page.MasterPageFile != null && page.MasterPageFile.ToLower().Contains("application.master"))
page.MasterPageFile = "/_layouts/CustomMasterPages/customApplication.master";
else
page.MasterPageFile = "/_layouts/CustomMasterPages/custom.master";
}

public void Dispose()
{
}
}

As you can see I use the PreInit event of the Page to change my masterpage to either the application masterpage or either the normal masterpage. I do this because the application masterpage needs to have 2 more contentplaceholders than in the regular default.master. For more information on this, take a look at Toms blog (references at the bottom of this post)
So what happens when we load a page: The page goes through its cycle and enters the PreInit fase, where this code kicks in and changes the masterpage accordingly.

Note 1: It isn't officially supported to change your default application.master
Note 2: It is possible that your Page already implements the PreInit. If this happens this code won't be run. F.e.: Most (if not all) publishing pages use the PreInit to change the masterpage to that of the currentWebs selected masterpage.

Step 3:
Strong name your dll, build it and put it in your global assembly cache (GAC)

Step 4:
Register your HttpModule in the web.config
Open your web.config and place the following line just before the </httpModules>:
<add name="MyModule" type="MyNameSpace.MasterPageModule, ##### Fully qualified name #####" />
To find your fully qualified name I would recommend using Red Gate's Reflector, I put the link to it in a previous post.

Step 5:
Enjoy.. that's all! Since we changed the web.config, doing an iisreset (or recycling the application pools) is not needed anymore. Whenever a change to the web.config is saved IIS does this automatically for you.

Note:
If you have pages made with the publishing contenttypes chances are very high that there will be an OnPreInit event already firing on the Page itself, thus overriding your own modules onpreinit.. be wary of this!

Some references on masterpages:
- http://jopx.blogspot.com/2007/09/ten-things-you-should-know-about.html
This is a good reference on masterpages in sharepoint in general, very recommended

- http://tomblog.insomniacminds.com/2007/10/29/sharepoint-branding-issues-application-pages/
A good reference on how to customize application masterpages

- http://support.microsoft.com/kb/307996
How to make a httpModule

2 opmerkingen:

Tom zei

Nicely done Jeroen! I like the sneaky way you alter the OnPreInit. Gotta love that event! :p

It's a shame that httpmodules aren't that easy to deploy. You could write some web application feature though to register your module directly.

I would have set a check on the url (to look for a _layout page) before adding the new event. Also you could pass the old event to the new event as a parameter in order to call the old one in the new one. (anybody still following? :p)

Anyway, excellent post!

Jeroen Van Bastelaere zei

Yes indeed, in my final version which I made for the client I also check for _layouts master pages so some dialogboxes also work (I believe it was for the addWebPart dialog box).
And ofcoursel changed it to comply with the coding guidelines (instead of 10001 I put that in the constants with something like WEBTEMPLATEID_PRIVATESITE)