Customisation, Technical
October 6, 2008

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



Enlarge Image

Written by: ggalipeau

Introduction

This is the third 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. Options to 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 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:

  1. Edit the master page in SharePoint Designer
  2. 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:

  1. Design - WYSIWYG editor
  2. Code - html editor
  3. 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

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

    5. <div class=”ms-CommentFooter”>Copywrite RDA all rights reserved 2008</div>

  5. Save the file.

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

  6. 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”.
  7. 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.

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

    2. <div class=”custom-footer “>Copywrite RDA all rights reserved 2008</div>

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

  3. Set the properties of the style
    • Selector = .custom-footer
    • Font
      • Font-family = Verdana
      • Font-size = x-small
      • Font-style = italic
  4. Click Ok on the style popup
  5. Save the file
  6. 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”.
  7. Open your site in a web browser to see the changes

Modify a SharePoint Control

  1. Find the top menu in the code view

    2. <SharePoint:AspMenu
    ID=”TopNavigationMenu”sdgds
    …

  2. Change the Orientation to Vertical

    3. Orientation=”Vertical”

  3. Save the file
  4. 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”.
  5. 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

  1. Find the text “ms-globalbreadcrumb” in the code.
  2. Right click on it.
  3. 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

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

  4. Save the css file

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

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

This entry was posted on Monday, October 6th, 2008 at 10:30 am and is filed under Customisation, Technical. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.
About the Author

Greg Galipeau

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

Viewing 10 Comments

 

Trackbacks

(Trackback URL)

close Reblog this comment
Powered by Disqus · Learn more
blog comments powered by Disqus


SharePoint Magazine

Support SharePoint Magazine

Technical

Everything You Need to Know about BDC: Part 1 of 8

Products

Visual Fusion Brings Location Intelligence to SharePoint

People

SharePoint Magazine chats to Mike Fitzmaurice about Nintex Reporting