The product of many evenings in hotels recently, I’m proud to present, my Application Master Page Changer.
Application master pages are tricky – out of the box in SharePoint 2007, there is no way of changing the master page used for ‘administrative’ pages. Unfortunately, those administrative pages include things like the recycle bin, file upload, and the ‘View all site content’ pages – things that users will likely see.
Well, folks have found a solution to this - using an HTTPModule to intercept pages using the normal application.master and redirecting it to use your custom one. This works pretty well, but I was always a bit uncomfortable – what if you only want this to happen for particular site collections, or specific sites within a Web Application? What if you want to use many alternate master pages? Most examples are hardcoded to one, and on throughout the web app. There is also the question of pushing the module out to all front-end web servers and putting the config entries you need into web.config – this never gets mentioned.
I’d tried knocking up an HTTPModule to forward to certain master pages for certain URL patterns, but it was awkward to configure, complex, and adding new sites/site collections could be a bit annoying – basically, a nightmare to configure. Installation was fairly manual, too.
What we really need, I thought, is some way of just turning on/off the master pages being used with Features. And that’s what I’ve built!
This is not a full solution – it couldn’t be, I don’t know what master pages you want to use! Rather, it’s an example, and most developers would be able to build a solution based on this in very short order. It will allow you to replace the application.master and simple.master pages either for all sites in a site collection, or for just a specific site. There are other master pages but I chose to ignore them – you could add support for them easily enough based on what I’ve built.
The project in this zip file is a Visual Studio 2008 project built with the fantastic WSPBuilder Extensions – I strongly recommend using them in your SharePoint development. Anyway, the solution contains 5 main elements:
- WebConfigFeature – This Web Application-level feature adds the HTTPModule to the Web.Config file for the web application it is active in.
- SPSiteChangerFeature – This Site Collection-level feature sets the path to the simple.master and application.master files for the site collection it is active in. Paths to the new master pages are set in the Feature.xml.
- SPWebChangerFeature – The Site-level feature set the path to the simple.master and application.master files for the site it is active in. This overrides the SPSiteChangerFeature if it is active. Paths to the new master pages are set in the Feature.xml.
- Burns.Andrew.MasterPageChanger.ChangerHTTPModule – The master page changer HTTPModule itself!
- The Master Pages to go in the LAYOUTS folder
How does it work?
Well, when you install the WSP, the Burns.Andrew.MasterPageChanger.dll assembly will be put in the GAC. Activating the WebConfigFeature will change the Web.config file to add that HTTPModule to the processing pipeline. Every page request will be checked to see if it uses simple.master or application.master. If it does, the ChangerHTTPModule will open the site collection and site at that URL, and check their properties. If they’ve got the properties set by the SPSiteChangerFeature or SPWebChangerFeature, then the ChangerHTTPModule redirects the request to use the appropriate master pages.
This approach has several advantages:
- Customisation can be turned on or off at a Site Collection or Site level. You could even change this to work for an entire Web Application too, but that didn’t seem worth the effort.
- Several brands can be supported by the same HTTPModule – it reads the master page it should use from the properties on the Site/Site Collection. You could create multiple versions of the SPWebChangerFeature and SPSiteChangerFeature features setting different master pages to be used.
- Minimal changes to the web.config file – and all changes are automatically rolled out across your servers.
So, hopefully this will allow your developers to turn out custom master pages for Application Pages and plug them together into a solution reasonably quickly.
Installation
- Install as normal for a WSP.
- In Central Admin go to Application Management > Manage Web Application Features.
- Activate the feature Burns.Andrew.MasterPageChanger.WebConfigFeature for the web application.
- Go to the Site Collections/Sites within that web application at turn on features as required.
I downloaded the code and applied it in my dev environment. It properly added the items to the web.config files, but when I look at the sites and go into the administration area, it appears that the swap is only happening on one of the two web front ends. The front ends are being used in an alternating session manner. I marked the master pages so I could see which server was being served. It seems to be working OK on the server where I ran the wsp. The other one is not doing it. I can’t see why this is the case. I tried re-adding the dll to the GAC, but that did not fix it. Any Ideas??
Not many – but it sounds like the WSP didn’t deploy properly across the apps. Did you check the web.configs? Do they both have an entry for the master changer HTTPModule?
It is very weird. The changes get made properly in the web.configs, the dll is loaded into c:/windows/assembly on both machines. The features show in the site admin for both servers. I loaded the wsp into my QA farm and it is working on both machines, so it does not appear to be a code issue.
This is working fine……Thanks for this post…….This is very helpful
Hi,
This is not working properly for me. the custom application master is not getting applied always. I mean when i open the “Site Settings” page through site actions menu its not showing up the customizations but when i come back from a page like SITE FEATURES page through bread crumb its showing up correctly. Please help me out
Hi,
I am also running into the same issue as Kalaravi. It is “working” on some pages but not in others. Any advice would be greatly appreciated! Thank you. kit_mx1@hotmail.com.
Can you be more explicit in how to install this? I am relatively new to sharepoint and I don’t know where to go after activating the feature.
What else do i need to do and can I have screenshots?
Hi Jeremy,
I take it that you read the part about it not being a full solution? To choose your new master pages you’d set the properties in the feature/s that you’d write and turn on at a Web site level or Site Collection level.
Open up the feature.xml files for those features, and it should become more obvious.
Kay, a little more detail would be good – is there a pattern to the pages it works on/doesn’t work on.
Andy,
Thank you for your response. Yes, I am seeing that some pages don’t work if you follow a path on getting to that page. For example:
DOES NOT Work:
Go to site http://localhost/Team/default.aspx
Click on site actions -> site settings
http://localhost/Team/_layouts/settings.aspx does not work
DOES work:
Go to site http://localhost/Team/default.aspx
Click on the Site Libraries and Lists link
You get to http://localhost/Team/_layouts/mcontent.aspx (this page looks good)
Then, from the breadcrumb, click on site settings
You get to http://localhost/Team/_layouts/settings.aspx — same page as above but it works now.
This is consistent. I am also observing similar behavior on similar pages.
I think what you built is great. Thank you for your help. kit_mx1@hotmail.com
I’ve been playing around with it. I had not activated it on the site collection level. I activated the features in the parent site and that seemed to do the trick. Now it seems it is working. I will continue playing with it.
Andy,
I also noticed that it does not work on publishing templates Pages/Default.aspx pages. Any ideas? Thank you!
Kay
kit_mx1@hotmail.com
Well, the path followed shouldn’t make a difference – the HTTP Module checks each request independently. It has no idea of where you came from.
That’s pretty weird, I’m afraid I don’t have any good ideas. Do you have multiple servers? It wouldn’t be something to do with caching and/or machine affinity would it?
Hi Andy,
No, I only have one box. It seems to happen when I use the navigation. When I type the URL in the browser, everything is ok. This is weird. Maybe something is happening with the caching as you mentioned. No one else ran into this issue? I guess it might be me. OK, I will continue looking at it. Thank you.
I ran into a “File not found” error trying to set the master pages to ones outside of the site collection. I fixed it as follows:
Essentially sites can’t reference master pages outside of the site collection, so I fixed the url in four spots. (in SPWebDefaultChangerFeature and in SPWebChangerFeature)
Two to fix the meeting workspace, two to fix the publishing site
The url should be like this:
//meeting_master = “//_catalogs/masterpage/custommeeting.master”;
Not like this:
/_catalogs/masterpage/custommeeting.master
//the master page must be within the site collection, jbeck
//get the site collections url
SPWeb rootweb = web.Site.RootWeb;
//append meeting_master on the end
String relativeUrl = rootweb.Url.Replace(“https://”, “”);
relativeUrl = relativeUrl.Replace(“http://”, “”);
if (relativeUrl.IndexOf(‘/’) > 0)//not root
{
relativeUrl = relativeUrl.Substring(relativeUrl.IndexOf(‘/’));
meeting_master = relativeUrl + meeting_master;
}
web.CustomMasterUrl = meeting_master;
web.Update();
i cant get this to work with SharePoint 2010, any ideas?
Um, yes. This isn’t necessary in Sharepoint 2010 – you can change the master pages used for application pages using standard functionality.