This is the third article in a six-part series on ASP.NET Master Pages and SharePoint.
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:
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.
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 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:
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.
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:
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.
<div class=”ms-CommentFooter”>Copywrite RDA all rights reserved 2008</div>
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.
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.
<div class=”custom-footer “>Copywrite RDA all rights reserved 2008</div>
<SharePoint:AspMenu
ID=”TopNavigationMenu”sdgds
…
Orientation=”Vertical”
(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).
.ms-globalbreadcrumb{
font-size:8pt;
text-align:right;
background-color:#000000;
padding:2px 10px 2px 5px;
}
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.
(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).
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:
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.
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”.
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.
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.
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.
I am currently a Project Manager at RDA Corporation (don’t worry – PMs at RDA do a lot of architectural work to). In addition I am also the IW/Collaboration Evangelist Team Leader at RDA. The IW/Collaboration Evangelist Team at RDA is dedicated to the growth and knowledge of SharePoint and other collaboration tools within Microsoft. I have been working with SharePoint since 2001 and have been involved in numerous custom application efforts centered around SharePoint during my employment at RDA. I have been coding in .net since it came out and am Microsoft Certified – MCPD, MCSD, MCAD, MTS (SQL Server 2005), MTS(SharePoint).
Contact the author | Other Posts by ggalipeau (5) | Author's Website
Add New Comment
Viewing 10 Comments
Thanks. Your comment is awaiting approval by a moderator.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Do you already have an account? Log in and claim this comment.
Add New Comment
Trackbacks
(Trackback URL)