Master Pages and SharePoint
Uploaded by
Julio Cesar Hilario LimaMaster Pages and SharePoint
Uploaded by
Julio Cesar Hilario LimaASP.
NET Master Pages and SharePoint
by RDA Project Manager Greg Galipeau
Contents:
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. Deploying a Master Page
5. Customizing the Application.master Page
6. Incorporating a Master Page into a SharePoint Site Definition
Part 1: Introduction to Master Pages
In this section, we will discuss the structure and architecture of an ASP.NET Master Page. We will show
ASP.NET Master Pages basic concepts in order to gain an understanding of how the pages work. This
section will lay the groundwork for the subsequent sections.
What is a Master Page?
Master Pages were introduced in version 2.0 of ASP.NET. Master Pages are a template that other pages
can inherit from to keep consistent functionality. The pages that inherit from Master Pages are referred to
as content pages. Master Pages allow the ASP.NET developer to keep consistent, reusable, Web-based
code (html, css, javascript, etc.) in one high level place, so the content pages can concentrate on their
specific web-based code. This allows for easily manageable Web-based applications.
Master Pages are architected with a merging concept. A content page refers to a Master Page and the
ASP.NET framework merges the two pages together to make one page.
Master Page
Content Page
Re
ASP.NET Master Pages and SharePoint
su
ltin
gP
ag
Page 1 of 41
How does a Master Page work?
There are two things that help define an ASP.NET Master Page:
1. It contains the extension .master , e.g., a common SharePoint Master Page is default.master.
7. It has a Master Page directive at the top of the page: <%@Master language="C#"%>. This
replaces the more typical <%@ Page directive that you will see on most ASP.NET pages.
A Master Page contains the same type of Web code that is contained in an ASP.NET page. This includes
head, body, form and any other html tag.
<%@Master language="C#"%>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
<html id="HTML1" runat="server" xmlns:o="urn:schemas-microsoft-com:office:office">
<head id="HEAD1" runat="server">
<META Name="GENERATOR" Content="Microsoft SharePoint">
<META Name="progid" Content="SharePoint.WebPartPage.Document">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<META HTTP-EQUIV="Expires" content="0">
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/core.css" />
</head>
<body>
<form id="Form1" runat="server" >
<div>
Hello
</div>
The difference between a Master Page and regular ASP.NET is that the Master Page can have special
sections called ContentPlaceHolders. A ContentPlaceHolder is a place holder section that the content
pages can fill in for the Master Page.
Master Page
Content Page
<asp:ContentPlaceholder id=MyPlaceHolder runat=server>
<asp:Content id=MyContent ContentPlaceHolderId=MyPlaceHolder runat=server>
This is the content that will fill in MyPlaceHolder on the Master Page
</Content>
</ContentPlaceHolder>
Re
su
ltin
gP
ag
The Master Page is a combination of regular html tags and ContentPlaceHolders.
<%@Master language="C#"%>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
ASP.NET Master Pages and SharePoint
Page 2 of 41
<html id="HTML1" runat="server" xmlns:o="urn:schemas-microsoft-com:office:office">
<head id="HEAD1" runat="server">
<META Name="GENERATOR" Content="Microsoft SharePoint">
<META Name="progid" Content="SharePoint.WebPartPage.Document">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
<META HTTP-EQUIV="Expires" content="0">
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/core.css" />
</head>
<body>
<form id="Form1" runat="server" >
<div>
Hello
</div>
<asp:ContentPlaceHolder id="MyPlaceHolder" runat="server">
</asp:ContentPlaceHolder>
If the ContentPlaceHolder of a Master Page is empty, it will be filled in by the implementing content page.
Alternatively, the ContentPlaceHolder can have Web code inside of it, which will be used if implementing
content page does not implement the particular ContentPlaceHolder.
Content Pages
Content pages are the ASP.NET pages that implement a Master Page. Content pages are normal
ASP.NET pages that contain an attribute which informs the compiler that the pages should be merged
with a Master Page. This attribute is part of the page directive tag and is called the MasterPageFile.
<%@ Page Language="C#" AutoEventWireup="true" MasterPageFile="~/Site1.Master"
CodeBehind="Default.aspx.cs" Inherits="WebApplication1._Default" %>
Content pages contain content tags. Content tags let the compiler know which ContentPlaceHolders to
override the Master Page.
<asp:Content ID="MyContent" ContentPlaceHolderId="MyPlaceHolder" runat="server">
This is the content that will override the ContentPlaceHolder "MyPlaceHolder" from the
Master Page
</asp:Content>
The order of the content tags on the content pages is irrelevant. The Master Page determines the layout
of all the content. The content pages use content tags to fill in ContentPlaceHolders on the Master Page.
ASP.NET Master Pages and SharePoint
Page 3 of 41
Master Page
Content Page
<asp:ContentPlaceholder id=MyPlaceHolder runat=server>
<asp:Content id=MyContent ContentPlaceHolderId=MyPlaceHolder runat=server>
This is the content that will fill in MyPlaceHolder on the Master Page
</Content>
</ContentPlaceHolder>
Re
su
ltin
gP
ag
Content pages are not required to implement all ContentPlaceHolders of a Master Page. If a content page
does implement a ContentPlaceHolder, then the code inside the respective content tag will override the
ContentPlaceHolder section of the Master Page. However, if a Content Page does not implement a
ContentPlaceHolder, then the code within the ContentPlaceHolder on the Master Page will render on the
browser.
Putting the pieces together
The Master Page is a template that controls the layout of a site. Content pages take care of filling in the
content of predefined sections of the Master Page called ContentPlaceHolders.
Below is a wireframe of a Master Page:
LOGO
TOP Menu
Side Menu
ContentPlaceHolder1
ContentPlaceHolder2
ContentPlaceHolder3
ASP.NET Master Pages and SharePoint
Page 4 of 41
Master Page Code
<%@ Master Language="C#" AutoEventWireup="true" CodeBehind="Site1.master.cs"
Inherits="WebApplication1.Site1" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>Untitled Page</title>
</head>
<body>
<form id="form1" runat="server" style="width: 1200px" >
<div style="border:solid 1px">
Logo
</div>
<div style="border:solid 1px">
Top Menu
</div>
<div style="width:300px; height: 286px;float:left;border:solid 1px">
Side Menu
</div>
<div style="border:solid 1px; height: 286px;">
<div style="border:solid 1px; height: 124px; width: 400px;float:left; margin:10px">
<asp:ContentPlaceHolder ID="ContentPlaceHolder1" runat="server">
</asp:ContentPlaceHolder>
</div>
<div style="border:solid 1px; height: 124px; width: 400px; margin:10px">
<asp:ContentPlaceHolder ID="ContentPlaceHolder2" runat="server">
</asp:ContentPlaceHolder>
</div>
<div style="border:solid 1px; height: 124px; width:812px; margin:10px">
<asp:ContentPlaceHolder ID="ContentPlaceHolder3" runat="server">
</asp:ContentPlaceHolder>
</div>
</div>
</form>
</body>
</html>
Content Page Code
<%@ Page Language="C#" AutoEventWireup="true" MasterPageFile="~/Site1.Master"
CodeBehind="Default.aspx.cs" Inherits="WebApplication1._Default" %>
<asp:Content ID="Content1" ContentPlaceHolderId="ContentPlaceHolder1" runat="server">
This is the content that will override the ContentPlaceHolder "ContentPlaceHolder1" from
the Master Page
</asp:Content>
<asp:Content ID="Content3" ContentPlaceHolderId="ContentPlaceHolder3" runat="server">
This is the content that will override the ContentPlaceHolder "ContentPlaceHolder3" from
the Master Page
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderId="ContentPlaceHolder2" runat="server">
This is the content that will override the ContentPlaceHolder "ContentPlaceHolder2" from
the Master Page
</asp:Content>
ASP.NET Master Pages and SharePoint
Page 5 of 41
SharePoint and Master Pages
SharePoint is designed on the concept of Master Pages. Almost all of the out of the box ASP.NET pages
in SharePoint inherit from a Master Page. Thus, if you want to customize the look and feel of all the
SharePoint pages, you can do this by customizing Master Pages. This allows for a centralized place to
make customizations (instead of modifying every Web page in the entire SharePoint system).
The following sections will show you the Master Pages included in SharePoint and the best practices for
making customizations to SharePoint Master Pages. However, it is important to understand the basics of
Master Pages before trying to customize Master Pages in SharePoint.
ASP.NET Master Pages and SharePoint
Page 6 of 41
Part 2: Examining the Out of the Box Master Pages in SharePoint
Now that we have a general understanding of how master pages work, we can discuss how SharePoint
has implemented them. This section will discuss the out of the box master pages in SharePoint in order to
gain an understanding of how SharePoint customized the out of the box site. These same techniques will
be used to build our own, customized SharePoint sites.
Master Page Gallery
In the previous section, we described master pages and content pages. Content pages contain a
reference to the master page to determine the place holders to fill in. In an ASP.NET application the
master page can live on the file system so a direct reference can be made to a physical file on the
system. This same concept is possible in SharePoint; however that wouldnt take advantage of the
natural SharePoint structure.
SharePoint is based on lists/libraries. These are galleries in which multiple instances of particular
information can be added. The basic example of these is the document library. You can upload multiple
documents, edit individual documents, change metadata about documents, etc Lists/libraries give
SharePoint users access to information directly in the comfortable SharePoint webpage. The advantages
of this are that if you need to add a new item to a list/library you dont have to ask a developer to do it (like
a typical ASP.NET application).
SharePoint master pages have their own list/library called the Master Page Gallery. This is a location on
the site where a site administrator can access and modify SharePoint master pages. To access a
SharePoint master page gallery go to a SharePoint site collection, go to the Site Settings, then click on
the master page gallery.
The advantage of storing master pages in the SharePoint master page gallery is that you have easy
access to the master pages (even after the site has been deployed). You can make your changes to the
master page and then upload it to the master page gallery when you are finished. If your content page
already points to that master page, the end user will see your master page changes as soon as the newly
edited master page is checked in.
SharePoint Site Structure
SharePoint is built on a template structure. These templates are referred to as Site Definitions. You might
also hear the term Site Template, however that is a customization of a site definition thus it is still built
on the same principles.
Site definitions contain the pages you see on the SharePoint site with sections that can be modified. A
good example of this is when you choose to create a team site in SharePoint.
ASP.NET Master Pages and SharePoint
Page 7 of 41
When you choose to create a team site you are choosing to create a site based off the team site
definition. This site definition determines the pages that show in the site (for example: the default.aspx
page) and the initial content to fill the site in with.
The page that gets created in the site definition (for example: default.aspx), is a content page. In the first
part of this section, we discussed how content pages refer to a master page. Thus, the out of the box
content pages, within the SharePoint site definitions, have references to the master pages in the master
page gallery.
Dynamic Tokens
Previously, I mentioned that the SharePoint content pages refer to master pages from the SharePoint
gallery. This would lead one to assume that there is a hard coded path, to the master page, from the
content page.
However, if this is a hard coded path to the master page, then it can never be changed without modifying
the actual content page. But, SharePoint provides a way for the administrator of a site to switch the
master page through the UI.
This is a MOSS publishing feature, which is not available on WSS or a standard MOSS site. However the
underlying architecture is the same in every version (they just didnt give the user the ability to see this
screen in WSS and standard MOSS).
So, how does SharePoint accomplish this architecture? SharePoint has a master page token replacement
functionality that runs when you view a site.
There are 3 tokens available for SharePoint master page references:
ASP.NET Master Pages and SharePoint
Page 8 of 41
1. Dynamic Token - ~masterurl/default.master
8. Dynamic Token - ~masterurl/custom.master
9. Static Token - ~site/mymaster.master and ~sitecollection/mymaster.master
So, what is the difference between dynamic tokens and static tokens?
Static Token direct reference to a master page. If your aspx page is at
http://mysitecollname/mysitename/default.aspx and your static token is ~sitecollection/mymaster.master,
then your master page file has to live at http://mysitecollname/mymaster.master. Or, if you static token is
~site/mymaster.master then your master page has to live at
http://mysitecollname/myysitename/mymaster.master.
Dynamic Token - replacement reference to a master page. This means that SharePoint will replace this
string with the real reference to the master page when the screen renders. Basically there are two
settings for every site called MasterURL and CustomMasterURL. MasterURL maps to System Master
Page in the screenshot above. And, CustomMasterURL maps to Site Master Page in the screenshot
above. If SharePoint sees ~masterurl/default.master in your content page, then it replaces it with
whatever is in the MasterURL property. If SharePoint sees ~masterurl/custom.master in your content
page, then it replaces it with whatever is in the CustomMasterUrl property.
The Dynamic Token architecture allows SharePoint to replace the master page reference at run time.
Thus, SharePoint has the flexibility of providing UI screens for the end users to replace the master pages
(even though they only provide this UI on MOSS publishing pages). This functionality is also available
through code for any version of SharePoint. So, developers can do this programmatically if necessary
too.
Example from SharePoints team site definition:
<%@ Page language="C#" MasterPageFile="~masterurl/default.master"
Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage,Microsoft.SharePoint,Version=12.0.0.0,Cult
ure=neutral,PublicKeyToken=71e9bce111e9429c"
Types of Master Pages
There are three main types of Master Pages in SharePoint:
1. Site Master Pages
2. System Master Pages
3. Application Master Pages
Site master pages are usually used in SharePoint publishing site definitions, but they can be used for
any SharePoint version. These pages are used so the main page can have one master page while the
subpages and views use other master pages (example of a subpage is a view of a list or library). This is
needed for publishing pages because the main page, of a site or subsite, usually has the publishing
feature turned on while the other pages dont. These publishing UI functionalities are contained in the
master page, thus you need a separation of master pages between the main page and the subpages.
This technique is not specific to publishing pages. A good example of this is the meeting workspace site
in MOSS. This site definition is not a publishing site. However the main page is different than the
subpages. This is accomplished by making the main page a site master page.
Site master pages are defined by ~masterurl/custom.master in the content page declaration.
System master pages are used for most non-publishing sites and subpages in publishing sites. The
system master page is what you typically see when you go to a WSS site or a non-publishing MOSS site.
ASP.NET Master Pages and SharePoint
Page 9 of 41
System master pages are defined by ~masterurl/default.master in the content page declaration.
Application master pages are for all Layout pages. Layout pages are SharePoint administrative pages
that are typically seen when doing site administration. You can tell a layout page because the URL of the
site has _layout in it. Layout pages are static, file server pages that are not driven by the database like
other pages in SharePoint. We will discuss application pages in more detail in section 5 of this article
because of the difficulties involved in understanding and customizing them.
Application master pages can be found at: %Program Files\Common Files\Microsoft Shared\web server
extensions\12\TEMPLATE\LAYOUTS.
Examining the Default.master
In order to get an understanding of how SharePoint implements its master pages, we are going to
examine the default.master page. This is the master page used for the typical out of the box SharePoint
site. The default.master can be found at %Program Files\Common Files\Microsoft Shared\web server
extensions\12\TEMPLATE\GLOBAL. When a new SharePoint site is created, this master page is moved
from this 12 hive path to the master page gallery of the newly created site. Actually, moved is not the
appropriate word. In fact, SharePoint just keeps a reference in the master page gallery to the file on the
12 hive path. This is a concept called Ghosting or Un-customizing.
Now that we understand how SharePoint deals with the default.master page, we can look at what the
default.master page contains. This master page contains what any other master page would contain
html and ContentPlaceHolders.
The html in the default.master contains things such as:
ASP.NET menu control - for navigation (top)
Site Actions html - for editing the page
Design mode area for exiting out of edit mode
Search controls
Quick Launch area for navigation (left side)
All of the out of the box pages in SharePoint, know how to deal with the ContentPlaceHolders from the
default.master page. That is a hint for anyone thinking about how they can customize master pages you
want to use the same ContentPlaceHolders that the default.master contains.
Master pages for publishing sites
The publishing site is a MOSS feature that allows the SharePoint site to act more like an Extranet or
Internet (rather than just an Intranet). While a publishing site is not needed to create an Extranet or
Intranet, it provides a lot of functionality to make the process easier. One of these functionalities is the
ability to switch the master page from the UI.
ASP.NET Master Pages and SharePoint
Page 10 of 41
Another one of these functionalities is that SharePoint provides more master pages in the master page
gallery. These are out of the box master pages that make a SharePoint site look more customized.
This is customization tip #1: for a quick way to make a SharePoint site look less like SharePoint create
your site as a publishing site and pick one of the extra master pages provided for publishing sites.
The out of the box master pages for publishing sites can be found at %Program Files\Common
Files\Microsoft Shared\web server
extensions\12\TEMPLATE\FEATURES\PublishingLayouts\MasterPages. Just like the default.master,
these master pages are moved to the master page gallery of the SharePoint site when the publishing site
is created. Once again, just like default.master, the word moved is actually incorrect because
SharePoint technically keeps a reference to the master page on the 12 hive file system (the concept
called Ghosting or Un-Customizing).
Actually, these get moved to the master page gallery when the publishing feature of the SharePoint site is
activated. But, the publishing feature is activated when a publishing site is created, so it is appropriate to
say the publishing master pages get moved to the master page gallery when a publishing site is created.
Theory behind creating Custom Master Pages
You might think that you can just modify the default.master from the 12 hive, or one of the publishing
master pages, in order to customize a SharePoint master page. However, this is not recommended best
practice. The reason for this is Microsoft could put out a patch for SharePoint that replaces the out of the
box master pages, thus overwriting your changes.
However, you can modify the master pages by going to SharePoint designer and making your
customizations there. You might ask why can I do this in SharePoint designer and not to the file
directly? The reason is SharePoint designer UnGhosts or Customizes a page. Unghosting, or
ASP.NET Master Pages and SharePoint
Page 11 of 41
customizing, is the process SharePoint takes to break the reference to the physical file and makes a
virtual copy of that file for you to use directly within your SharePoint site. This is good practice for quick
changes. However, this forces you to code directly against a site, rather than wrapping it up in a good
solution (which should be done for development efforts in order to keep things deployable).
Thus, if you are not in a situation where you can make a change to the master page directly against the
site (i.e.: SharePoint Designer), then the process for customizing master pages is to create your own
master page and upload it to the master page gallery. Then re-point the master page reference on the
SharePoint page to your new master page. This concept will be demonstrated in the following sections.
ASP.NET Master Pages and SharePoint
Page 12 of 41
Part 3: Developing a Custom Master Page
In the previous two sections of this article, we discussed master pages and how SharePoint uses them to
create its 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 section, 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 section 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 cant 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
ASP.NET Master Pages and SharePoint
Page 13 of 41
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 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.: dont 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
ASP.NET Master Pages and SharePoint
Page 14 of 41
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, please
refer to the second section in this article - 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 shouldnt 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 wont show on the final page
ASP.NET Master Pages and SharePoint
Page 15 of 41
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, lets make some customizations so you can see some things that can be done.
Create a footer
1.
2.
3.
4.
Find the tag </Body> in your code view and put your cursor right before it.
Type the some footer text ex: Copyright RDA all rights reserved 2008.
Wrap the footer text in a div tag.
Set a class to the div tag. For example purposes we can use an out of the box css class from
SharePoint
<div class="ms-CommentFooter">Copyright RDA all rights reserved 2008</div>
5. Save the file.
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
<div class=custom-footer ">Copyright RDA all rights reserved 2008</div>
2. Select the new style link from the Apply Styles toolbar on the right
ASP.NET Master Pages and SharePoint
Page 16 of 41
3. Set the properties of the style
a. Selector = .custom-footer
b. Font
i. Font-family = Verdana
ii. Font-size = x-small
iii. 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
<SharePoint:AspMenu
ID="TopNavigationMenu"sdgds
2. Change the Orientation to Vertical
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
ASP.NET Master Pages and SharePoint
Page 17 of 41
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
.ms-globalbreadcrumb{
font-size:8pt;
text-align:right;
background-color:#000000;
padding:2px 10px 2px 5px;
}
4. Save the css file
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 dont 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 sections, 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.
ASP.NET Master Pages and SharePoint
Page 18 of 41
And remember; dont 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 UnGhosted this page at one point.
If you decide that you made a mistake by UnGhosting your file then you can undo your changes by reGhosting 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 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 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 section in
this article will show how to create custom master pages that can be uploaded to any SharePoint site for
easy deployments.
ASP.NET Master Pages and SharePoint
Page 19 of 41
Part 4: Deploying a Master Page
In the previous section, we discussed how to build a customized master page in SharePoint Designer. At
the end, we discussed that making the modifications directly in SharePoint Designer is not the most
deployable solution for production life cycle environments. This section will discuss the other option to
customize and deploy a master page for a production-ready system.
Features
Features are SharePoints way of activating and deactivating specific code on a particular SharePoint
website and/or site collection. Features may specify what webparts should be available, what lists should
be available, and what actions should be on list menus.
Features can also deploy master pages to the master page gallery of a SharePoint site and/or site
collection. Using a feature to deploy the master pages gives us reusable files that can be deployed to any
SharePoint environment through SharePoint commands. This means that we can create build scripts to
deploy our master page to a master page gallery. This is much better than the copy and paste method of
SharePoint Designer we showed in the previous section.
Features contain two main files:
1. Feature.xml When a feature is installed, SharePoint looks for the feature.xml file to determine
how to deploy the feature. The feature.xml file defines the feature and provides the paths to the
other files involved in deploying the feature.
2. Elements Manifest this file is referred to from the feature.xml. This is the file that determines
what the feature should do when it is activated.
Features can be installed to a SharePoint environment through stsadm commands. Stsadm is the
command line tool for SharePoint and is used for multiple administrative and development operations in
SharePoint.
Once a feature is installed on a SharePoint machine, it can be activated or deactivated on a particular
SharePoint site or site collection. Every feature.xml file contains a Scope attribute. If the scope of a
feature is Web, that means that the feature can only be activated at the SharePoint site level. If the
scope of a feature is Site, that means the feature can only be activated at the SharePoint site collection
level. Site Collections contain all the sites in a SharePoint tree. Thus, if a feature is activated at a site
collection, it is activated for all the sites in the site collection. If a feature is activated at a site, it is
activated for that site only.
To activate a feature you can go to a site and/or site collection and then go to the Site Settings. In the site
settings you will see a link for Site features. If you are on a top level site in the site collection, you will
also see a link for Site collection features.
When you click on the Site features and/or Site collection features link, you will go to the feature
activation page for the site and/or site collection, respectively. From this page, you can activate or
deactivate sites for the site and/or site collection.
ASP.NET Master Pages and SharePoint
Page 20 of 41
Custom Master Page file
To customize a SharePoint master page with a feature, you need to create a custom master page file.
This file gets uploaded to the master page gallery in SharePoint through the feature.
There are multiple ways to create your own master page files. Here are a few techniques I recommend:
1. Copy Technique:
a. Copy the default.master from %Program Files\Common Files\Microsoft Shared\web
server extensions\12\TEMPLATE\Global.
b. Make your changes directly to the html (in the copied file).
c. Make sure the copy file has a different name than default.master.
2. Designer Technique
a. Make your changes in SharePoint designer as described in the previous section.
b. Do not save these changes against your site you can do this against a test site to make
things easier.
c. Copy the html out into a custom master file and give it a unique name.
3. Minimal Master technique
a. Make a master page file with the minimal master html code found here:
http://msdn.microsoft.com/en-us/library/aa660698.aspx
b. The minimal master html is a master page with all the content place holders that you will
need for SharePoint. This is a good starting point if you want to start from scratch in
creating your master page. You should become familiar with what all the content place
holders are for when using this technique.
c. Save this file as a new master file and give it a unique name.
Create the Feature
Features are created in Visual Studio and then moved into the SharePoint 12 hive %Program
Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES. After the
feature is in the 12 hive, stsadm commands can be used to deploy the feature to the SharePoint
environment. Then the feature needs to be activated on the SharePoint site.
Steps to create a feature for Master Page deployment:
Note: We will not be using any tools like Visual Studio Extensions for WSS or WSPBuilder for this
walkthrough. However, I recommend using these tools to wrap the features in solutions. We will talk more
about this in the last section in this article.
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 DemoMasterPageFeature
5. Delete Class1.cs
6. Add a new folder to the project and call the folder 12
7. Add a new folder to the 12 folder, call it Template
8. Add a new folder to the Template folder, call it Features
9. Add a new folder to the Features folder, call it DemoMasterPage
10. Add a new folder to the DemoMasterPage folder, call it MasterPages
11. Add a new master page file to the MasterPages folder
ASP.NET Master Pages and SharePoint
Page 21 of 41
a. There are multiple ways to create this file
i. You can copy the one from SharePoint
ii. You can copy a modified one out of SharePoint Designer. Go to section 3 {insert
link here} and use the html we modified in SharePoint Designer for your new
master page file.
iii. You can start with a minimal master page http://msdn.microsoft.com/enus/library/aa660698.aspx
b. We are going to use the technique of copying the one from SharePoint
i. Go to %Program Files\Common Files\Microsoft Shared\web server
extensions\12\TEMPLATE\Global.
ii. Copy the default.master
iii. Paste it in the MasterPages folder (in the Visual Studio project)
c. Rename the file demomasterpage.master
12. Add a feature.xml file to the DemoMasterPage folder.
a. This file tells SharePoint how to install the master page
b. It must be called feature.xml
c. Put the following xml in it
<Feature Id="95F25D4A-D256-4158-96FE-010F599149CC" Title="Demo Master Page"
Scope="Site" Version="1.0.0.0" Hidden="FALSE" DefaultResourceFile="core"
xmlns="http://schemas.microsoft.com/sharepoint/"
Description="This Feature contains the demo master page">
<ElementManifests>
<ElementManifest Location="elements.xml" />
<ElementFile Location="MasterPages\demomasterpage.master" />
</ElementManifests>
</Feature>
d. Notice the following:
i. Scope this tells SharePoint where to install the feature. Our scope is site, thus
we want to install the feature at the site collection level. This is because our
master page gallery lives at the site collection level. If we wanted to install the
feature at the sub-web level, it would say web
ii. ElementManifest this tells SharePoint the other files involved in creating this
feature. Remember, SharePoint only knows to look at the feature.xml file when
installing a feature, so the feature.xml file must tell SharePoint about the other
files involved.
iii. Id this is the unique GUID for the feature. It must be unique. So, if you create
multiple features, make sure you use a unique GUID here. This is also how we
can reference the feature when we start building solutions.
13. Add an elements.xml file to the DemoMasterPage folder
a. This file tells SharePoint what to do with this feature. For example: we want to deploy our
master page to the master page gallery. This is the file that will tell SharePoint to do that.
b. It doesnt have to be called elements.xml. But, it does have to be called whatever you put
as the ElementManifest Location in the feature.xml file. I like to use elements.xml when I
create these files
c. Put the following xml in it
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Module Name="DemoMasterPage" Url="_catalogs/masterpage" Path="MasterPages"
RootWebOnly="FALSE">
ASP.NET Master Pages and SharePoint
Page 22 of 41
<File Url="demomasterpage.master" Type="GhostableInLibrary" />
</Module>
</Elements>
d. Notice the following:
i. Url this is how we tell SharePoint to put the file in the master page gallery.
_catalogs/masterpage is the location of the master page gallery when dealing
with site collections. We know we are dealing with site collections because the
feature.xml file has a scope of site.
ii. File this tells SharePoint the name of the file it is going to put at the master
page gallery. The type is GhostableInLibrary this means the file is still going
to be on the 12 hive and SharePoint is going to keep a Ghosted reference to the
file. Please refer to section 3 for more information about Ghosting.
14. Build the project in order to save your changes.
The final folder/file structure should look like this:
Deploying the Feature
There are two steps to deploy a feature:
1. Copy the contents to the 12 hive.
a. Copy the folder DemoMasterPage (this is the folder we created in the Visual Studio
solution in the last section). Be careful to only copy the DemoMasterPage folder, not all
the folders we created.
Also, you probably wont be able to copy from Visual Studio. So, go to windows explorer
to do the copy of the folder.
b. Paste the DemoMasterPage folder in %Program Files\Common Files\Microsoft
Shared\web server extensions\12\TEMPLATE\FEATURES.
2. Run stsadm commands to install the feature
ASP.NET Master Pages and SharePoint
Page 23 of 41
a. Open up a command prompt
b. Enter the following: cd C:\Program Files\Common Files\Microsoft Shared\web server
extensions\12\BIN.
Note: this assumes you installed SharePoint on your C drive. Please change the install
path if otherwise.
c. Enter the following: stsadm o installfeature name DemoMasterPage -force
Note: do not copy and paste. Sometimes copy and paste into command lines wont work.
Please retype in your command line
d. Enter the following: stsadm -o activatefeature -name DemoMasterPage -url
http://mysitecollectionpath -force
Note: do not copy and paste. Sometimes copy and paste into command lines wont work.
Please retype in your command line
i. The string after name is the name of feature of your feature folder.
ii. The url is the url to your site collection root. You can copy it from your browser,
but dont keep the default.aspx on the path
Whats wrong with this picture?
Any developer will say this is not correct. Developers dont want to copy files manually and paste them in
a folder. Yes, I understand this. I am showing this technique to lead up to the last section in this article on
solution deployment. The solution will take care of moving the files to the 12 hive and running the
commands for you. However, it is important to understand what solutions do before jumping right into
them. Thus, I am showing you this manual way so you can get an idea of what the solution is doing
behind the scenes.
ASP.NET Master Pages and SharePoint
Page 24 of 41
Set the new master page
The feature we just created placed the new master page in the master page gallery. However, it did not
tell SharePoint to use this new master page on your SharePoint site. There are multiple ways to do this
including: custom site definitions, programmatically setting the default master page, using SharePoint
Designer, or using the MOSS master page selection page.
If you are using WSS, please refer to section 3 in order to see how to set the master page in SharePoint
designer.
If you are using MOSS, you can go to your site collection and then go to site settings. Then under Look
and Feel click on the Master Page link. You can now choose the demomasterpage.master to be the
master page for your site collection.
Please Note: This assumes you have the Publishing feature turned on in MOSS. The Publishing feature
might be turned on and might not be turned on based on the site definition you used to create your site. If
the Publishing feature is not turned on in MOSS you will not see the Master Page link under Look and
Feel in the Site Settings page. To turn the Publishing feature on go to Site Settings, then look under the
Site Collection Administration column and then click the Site collection features link. Find the Office
SharePoint Server Publishing Infrastructure column and click Activate. Now, when you go back to the
Site Settings Look and Feel column you will see the Master Page link.
Making Changes to the Master Page
Now the Master Page has been installed to the SharePoint farm and activated on the site collection. So,
what if you want to make further customizations to the master page? Do you have to go through the
process of re-installing and re-activating? The answer is no. Here comes the power of ghosting. Please
refer to section 3 for more information about Ghosting. Since the master page is ghosted, the SharePoint
site keeps a reference to the 12 hive version of it. So, if you want to make a change to your master page,
all you have to do is update the demomasterpage.master file in the feature folder of the 12 hive
(%Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES).
Deactivating the Feature
Sometimes there are changes you need to make to a feature that are not ghosted. Examples of these
types of changes are things in the feature.xml file. You cannot change the id of a feature.xml file and
expect to be able to just re-install and re-activate the feature. Instead, you have to deactivate the feature
and uninstall the feature first. Here are the commands to do this.
ASP.NET Master Pages and SharePoint
Page 25 of 41
1. Open up a command prompt
2. Enter the following: cd C:\Program Files\Common Files\Microsoft Shared\web server
extensions\12\BIN.
Note: this assumes you installed SharePoint on your C drive. Please change the install path if
otherwise.
3. Enter the following: stsadm o deactivatefeature name DemoMasterPage url
http://mysitecollecitonpath -force
Note: do not copy and paste. Sometimes copy and paste into command lines wont work. Please
retype in your command line
4. Enter the following: stsadm o uninstallfeature name DemoMasterPage -force
Note: do not copy and paste. Sometimes copy and paste into command lines wont work. Please
retype in your command line
Conclusion
Using features to deploy the master page to the master page gallery is a reusable way to deploy master
pages in SharePoint. However, there are still manual processes involved (including copying files to the 12
hive). Thus, using features is not the complete story when dealing with SharePoint deployments. In the
last section of this article, we will discuss SharePoint solutions (WSPs). WSPs are basically CAB files that
wrap up features in SharePoint for easy deployment. The WSP file will move the feature files to the 12
hive for you. However, I think it is important to understand how this is done before jumping into creating
WSP solutions. Plus, we can reuse the feature we created in this section when we build the WSP solution
out in the final section.
ASP.NET Master Pages and SharePoint
Page 26 of 41
Part 5: Customizing the Application.master Page
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
section 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 sections, 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 dont take the necessary steps to make sure that application pages dont 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 doesnt 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.
Microsofts recommendations for customizing application.master
According to this support site: http://support.microsoft.com/kb/944105 - there are two ways to
modify/customize the application.master page.
1. Modify the application.master page in the 12 hive But remember, you are NEVER supposed 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 cant have two Web applications on a server that
look different.
2. 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..
For the reasons listed above, I dont particularly agree with either of these recommendations.
Luckily, others within 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.
ASP.NET Master Pages and SharePoint
Page 27 of 41
This approach is a non-supported approach, but the SharePoint framework leaves us few options.
Besides, the supported approaches above seem to do more damage than good, so I can live with nonsupported 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, from whom he originally got the idea to dynamically replace master pages 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);
}
ASP.NET Master Pages and SharePoint
Page 28 of 41
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
a. Right click on the ApplicationHttpModule project and go to the properties
b. Go to the Signing link on the right side
c. Click the checkbox to Sign the assembly
d. In the Choose a strong name key file dropdown, choose <New>
e. Enter a Key file name.
f. Uncheck the Protect my key with a password checkbox
g. Click Ok
8. Build the project
9. Place the dll in the GAC
a. If you built in Debug mode then the dll will be at: <project
path>/bin/debug/ApplicationHttpModule.dll
b. 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 dont remember where it is, the best way to figure it out is to go into
IIS, find your website, go to the properties, and click on the Home Directory tab. Your path will
be in the Local path text box.
ASP.NET Master Pages and SharePoint
Page 29 of 41
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" />
Please note the following:
-
Type=<class name including namespace>, <name of assembly>
PublicKeyToken This can be found by going to the dll in the GAC (C:\Windows\assmebly).
Next, 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 like. But, you still have to be careful about keeping the content place
holders around.
Be Careful
Just like the regular SharePoint master pages, you must still be careful when you start modifying
application master pages. Here are a few final tips to keep in mind:
-
Dont 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 dont remove it just wrap it in a tag and turn
the visible property to false.
You cant have a search control on the application master pages. I am not sure of the reason
for this, but you cant 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-aroundmicrosoft-bugs/
Do not use this method if your install has the SSP on the same server as the main
SharePoint application. SSP has reported issues with this approach because the system
master pages they use have a different setup.
ASP.NET Master Pages and SharePoint
Page 30 of 41
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.
ASP.NET Master Pages and SharePoint
Page 31 of 41
Part 6: Incorporating a Master Page into a SharePoint Site Definition
In the previous section of this series we discussed how to build a customized master page and deploy it
with a feature. However, the manual process of deploying the feature to each server in the farm and
activating it isnt as seamless as most developers would like. It would be nice to have the features
automatically activate themselves when a new site in SharePoint is created from a template.
This section will discuss the creation of SharePoint site definitions, which are templates for SharePoint
sites that will automatically create the master page feature on the site when created.
Site Definition
Site Definitions are templates that developers can build in SharePoint. You might also hear the term Site
Template in SharePoint, which is a customization of a Site Definition. In order to clear up any confusion
on these two terms, you can just think of them like this:
Site Definitions SharePoint template that developers can create to manipulate how a site should
be created. These are stored in the 12 hive of SharePoint and are referenced during site creation.
Site Templates Customization of a Site Definition that administrators of the SharePoint site can
create from the UI screens. These are stored in the content database and these are not meant for
developers to manipulate.
When you create a SharePoint site and use one of the out of the box templates, you are actually using a
Site Definition that Microsoft created and shipped with the SharePoint product.
WSP Solutions
In the fourth section of this article, we discussed the manual process of creating a feature, placing it in the
12 hive and deploying it with stsadm commands. While that is a valid process to deploy to SharePoint, it
is a very manual process. Also, we are now bringing another factor into our project (i.e.: the Site
Definition). So, we could manually deploy the site definition in addition to the feature, but now we are
starting to have a lot of manual steps. Plus, if we have a large SharePoint farm, we are going to have to
repeat these steps on each server.
Thus, SharePoint created a way to incorporate all your features, site definitions, etc into one deployable
solution. These solutions are called WSP files. WSP files are basically CAB files with an extension
SharePoint understands so it can deploy to a SharePoint farm. These solutions automatically get
deployed to all appropriate servers in the farm. Thus, you only have to install the WSP against the
SharePoint web application in order to install all your features, site definitions, etc.
What are we showing in this section?
In this section we are going to show how to create a Feature, Site Definition and WSP solution.
The Feature will deploy the master page to the master page gallery of our site.
The Site Definition will create the template for our site. This template tells SharePoint which aspx pages
to create, which web zones to create, what features to activate, etc.
Lastly, the WSP solution will wrap everything up into one deployable package.
One question that undoubtedly comes up is, Why are you incorporating the feature into the site definition
instead of using feature stapling? Feature stapling is the process of creating features and stapling them
to Site Definitions that already exist. For example, lets say you created a Web part in a feature and you
wanted that feature to be activated on all sites created with the WSS team site definition that comes out
of the box in SharePoint. However, you want to keep all the other parts of that site definition intact; all you
ASP.NET Master Pages and SharePoint
Page 32 of 41
want to do is add one more feature onto it. With feature stapling, you can create a feature and tell it to
attach itself to pre-existing site definitions (even the ones that come out of the box in SharePoint).
The decision to use feature stapling versus custom site definitions has to deal with the amount of
customizations you need to make. There might be times when you want to use feature stapling instead of
brand new site definitions. However, in a lot of cases you need to make changes that go above and
beyond just the features in a site definition. Thus, it is good to create custom site definitions to manipulate
these functionalities. Plus, custom site definitions activate the features when the site collection is getting
created, while feature stapling activates the features after the site has been created. This timing is
important to understand in some complicated situations.
So, for this particular demo I am going to activate my master page feature in a custom site definition to
show the process. But, I am not saying this is the best way. If you already have a site created and just
need to deploy the master page feature, you might want to look into feature stapling as an option.
What tools are we going to use?
One of the more difficult things to understand when you first learn how to create WSP solutions is the
install files that are needed to build the WSP solution. These files are called the manifest and the ddf files.
These files basically explain to SharePoint what features, site definitions, etc. is part of your solution so
that SharePoint can install the solution to the Web application.
Since these files are difficult to understand, there are a lot of third party tools available that will build the
manifest and ddf files for you. These tools are usually extensions to Visual Studio. Microsoft built one
called Visual Studio Extensions for WSS. Plus, there are many open source ones on CodePlex including
STSDEV, SPBuilder, WSPBuilder, etc. Each of these tools provides a different approach to building
SharePoint solutions.
My personal favorite is WSPBuilder. The way this product works is it mimics the 12 hive in a Visual Studio
solution. As long as your Visual Studio solution has the same folder structure as the 12 hive, it will build
the correct files to create the WSP solution. This is very powerful and flexible. I like this over the Visual
Studio Extensions for WSS because I feel that I am restricted in what I can do with Visual Studio
Extensions for WSS.
The choice of the solution builder tools you want to use is a personal choice. For this example I am going
to work with the WSPBuilder add-in for Visual Studio.
ASP.NET Master Pages and SharePoint
Page 33 of 41
Here is an example of how WSPBuilder works. Notice that the servers 12 hive matches the Visual Studio
solution:
Servers 12 hive
Visual Studio Solution
As long as the 12 hive matches, you can right click on your project and use the WSP Builder menu
options to build your WSP file.
ASP.NET Master Pages and SharePoint
Page 34 of 41
Also, when you are developing on a SharePoint server, you can right click on your project and use the
WSPBuilder menu options to deploy your WSP file to the local server. This will deploy it to all Web
applications on your development machine.
Thus, when you are developing, you should be developing on a SharePoint server. Virtual machines such
as VPC or VMWare are great for this. Then, every time you make a change you can just go to the deploy
menu option of the WSPBuilder menu. After you are finished developing, you can build the WSP file using
the menu options and it will physically place the WSP file in your projects folder. At this point you can
copy that WSP file to the production machine and deploy it with stsadm commands.
Walkthrough
Create The Structure
-
Start Visual Studio and choose a new WSPBuilder project.
Create a folder structure for the solution that matches the folder structure for the SharePoint 12
hive (this is really important - WSPBuilder works on the premise that the Visual Studio solution
matches the structure of the SharePoint 12 hive). For now we are just going to create the
following folders:
o
o
o
o
o
Template - subfolder under 12 that holds the other subfolders
1033 holds the xml files that will tell SharePoint about our new site definitions
Features holds the new features we are going to build (i.e.: lists, webparts, master
pages, etc)
Layouts holds our reference files (i.e.: images, css, js, etc)
Site Templates holds our site definitions
ASP.NET Master Pages and SharePoint
Page 35 of 41
Create a Site Definition
-
Create a new site definition based off the team site definition in SharePoint.
o Copy the team site definition folder from the 12 hive:
C:\Program Files\Common Files\Microsoft Shared\web server
extensions\12\TEMPLATE\SiteTemplates\sts
o Paste the folder in the Visual Studio solutions SiteTemplates folder.
o Rename the sts folder to something unique (DemoCompanySiteDef for this example)
Delete the defaultdws.aspx file because we arent going to use it for this example.
Open the default.aspx file and change the master page to a new master page. Call this custom.master
(yes, I know that this is not the name of our master page. We are going to configure SharePoint to do a
string replacement of custom.master with DemoCompany.master in later steps). We will create this
master page in the next step.
4.
Modify the Onet.xml file of the Site Definition for initial preparation
-
Open the Onet.xml file (located in the xml folder) and clean it up for our simple site definition.
ASP.NET Master Pages and SharePoint
Page 36 of 41
The Onet.xml file is the file that tells SharePoint how to create the site definition. Whenever you
create a new site in SharePoint it reads from the Onet.xml file to determine how to create the site.
It is important to note that SharePoint is reading from the Onet.xml file when the site is being
created. So, if you already have created a site, you cant go back to the Onet.xml file, make
changes, and expect it to show up on your already created sites.
-
Scroll down to the Configurations XML nodes and remove 2 configurations:
o ID=1 - Blank
o ID-2 DWS
Be very careful not to remove ID=0 Default, because this is the configuration we are
going to use for this site definition. When removing the other two get rid of the whole xml
tag as well as everything within their xml tag.
Scroll down to the Modules XML nodes and remove 2 modules:
o DefaultBlank
o DWS
Once again, be very careful not to remove the Default module because this is the module we are
going to use for this site definition. When removing the other two get rid of the whole xml tag as
well as everything within their xml tag.
Create the new master page feature
The master page will be created as a feature. The reason for this is that if the master page is in a feature
the master page can be added to the master page gallery of SharePoint. This allows you to set out-of-thebox pages to the master page or your own custom site definitions. It also allows you to turn on or turn off
the master page features on specific sites. Basically, having it in a feature (rather than directly in the site
definition or in the layouts folder) gives you much more flexibility.
-
Create a new folder under FEATURES and call it something unique for your master page. For
this example we will call it DemoCompanyMasterPage.
Create a folder under the DemoCompanyMasterPage called MasterPages.
o Copy the general SharePoint master page from the 12 hive: C:\Program Files\Common
Files\Microsoft Shared\web server extensions\12\TEMPLATE\GLOBAL\default.master
o Paste the file under the MasterPages folder in the Visual Studio solution.
o Rename the file to something unique (DemoCompany.master for this example).
Create two xml files under the DemoCompanyMasterPage folder.
o feature.xml this will give a unique GUID to the feature (which we will reference later).
This file also gives some important information about the Scope of the feature. Lastly, this
file tells SharePoint where all the other files that make up this feature lives. This file must
be called feature.xml (this is because SharePoint will read all files called feature.xml from
the Features folder).
<Feature Id="95F25D4A-D256-4158-96FE-010F599149CC" Title="Demo Master Page"
Scope="Site" Version="1.0.0.0" Hidden="FALSE" DefaultResourceFile="core"
xmlns="http://schemas.microsoft.com/sharepoint/"
Description="This Feature contains the demo master page">
<ElementManifests>
<ElementManifest Location="elements.xml" />
<ElementFile Location="MasterPages\DemoCompany.master" />
</ElementManifests>
ASP.NET Master Pages and SharePoint
Page 37 of 41
</Feature>
Please note that the Scope=Site. This is very important. This is telling SharePoint that this
feature is for the site collection. If that Scope=Web then it would be telling SharePoint that this
feature is for an individual site.
o
elements.xml this file is telling SharePoint to place the new master page into the master
page gallery. This file does not have to be called elements.xml (unlike the feature file
which has to be called feature.xml). It just has to match the name located in the
ElementManifest of the feature.xml file.
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Module Name="DemoCompanyMasterPage" Url="_catalogs/masterpage" Path="MasterPages"
RootWebOnly="FALSE">
<File Url="DemoCompany.master" Type="GhostableInLibrary" />
</Module>
</Elements>
Modify Onet.xml file of the Site Definition
We are modifying the Onet.xml file of the Site Definition in order to tell this Site Definition to activate our
Master Page feature when the site is created and to use our custom master page with the dynamic url
replacement technique.
Dynamic Token URL replacement
-
Open the onet.xml file in Visual Studio (located at SiteTemplates/DemoCompanySiteDef/xml).
Find the xml node that says Configuration ID=0 Name=Default.
Add in a reference for the new master page:
<Configuration ID="0" Name="Default"
CustomMasterUrl="~SiteCollection/_catalogs/masterpage/DemoCompany.master"
MasterUrl="~SiteCollection/_catalogs/masterpage/DemoCompany.master">
Note: SharePoint will do a string replacement of any aspx page with ~masterurl/custom.master with
the reference in CustomMasterUrl. And, it will replace any aspx page with ~masterurl/default.master
with the reference in MasterUrl.
Activate the Feature
-
Find the SiteFeatures XML node.
Add a new Feature node in there that matches the GUID of the feature.xml file we created for our
master page.
ASP.NET Master Pages and SharePoint
Page 38 of 41
This section of the onet.xml tells the site to activate this particular feature on this particular site when it is
being created. The reason it goes into the SiteFeatures (instead of the WebFeatures) is because this
particular feature was scoped for a Site Collection. If the feature was scoped for an individual site then it
would go in the WebFeatures.
Create the WebTemp*.xml file
WebTemp*.xml files tell SharePoint about site definitions. When a new site is being created in SharePoint
the Select Templates list box is populated by anything it can find in the WebTemp*.xml files. There can
be multiple of these files in SharePoint as long as they are in the 12/Template/1033/XML folder.
SharePoint will basically read this folder for any file that starts with the word WebTemp.
-
Add a new folder under 12/Template/1033 in our Visual Studio solution called XML.
Add a new file to the 12/Template/1033/XML folder in our Visual Studio solution. This file must start
with WebTemp. We will call this file WebTempDemoCompany.xml.
Add in the proper xml to tell SharePoint about our new site definition
<Templates xmlns:ows="Microsoft SharePoint">
<Template Name="DemoCompanySiteDef" ID="10051">
<Configuration ID="0" Title="Demo Company Site"
Hidden="FALSE"
ImageUrl="/_layouts/images/stsprev.png"
Description="A site for the Demo Company"
DisplayCategory="Demo Company" >
</Configuration>
</Template>
</Templates>
A few things to note:
1. The Name must match the site definition folder exactly. We used the name
DemoCompanySiteDef. This matches our site definition name exactly.
2.
3.
4.
The Configuration ID must match the configuration ID in our onet.xml file of our Site Definition.
We used configuration id 0.
The display category will create a new tab on the new site screen in SharePoint.
The ID has to be unique and SharePoint has already reserved certain IDs. To be safe use an ID
over 10000 and make sure it is unique.
ASP.NET Master Pages and SharePoint
Page 39 of 41
Use WSP Builder to build and deploy the solution
Now, at this point (in a regular SharePoint solution) we would create manifest.xml and ddf files. These are
files SharePoint needs to install the solution properly. However, since we are using WSPBuilder, it will do
that for us.
-
Right click the project and click WSPBuilder Build
Verify your Web Application is created on your local SharePoint environment. Note: the Site
Collection should not be created at this point, just the Web Application. And, you only need to do this
once.
If the build is successful, right click the project and click WSPBuilder Deploy.
This is needed because the build command in WSPBuilder just builds a wsp file. This file can be sent
to other machines and you can use stsadm scripts to install it on other SharePoint farms. However, in
development, we need a quick way to deploy it to the current SharePoint farm. The WSPBuilder
Deploy command will deploy the wsp file on all the Web Applications in the local SharePoint farm.
Use the Site Definition
Open up SharePoint Central Administration and create a new Site Collection with the site definition we
just created.
Now you can go back and modify the master page or default.aspx page as you wish. Just be careful not
to mess with the ContentPlaceHolders too much. SharePoint reserve these for certain actions on some of
its internal pages. After every change you make you can rebuild by clicking WSPBuilder Build and
update the solution by clicking WSPBuilder Deploy. Then you can just go to the website and see your
changes. Just be aware that everytime you deploy WSPBuilder does an app pool recycle (to ensure the
changes get pushed out through IIS), so you might have to wait a few seconds to see your changes
(during that few seconds the site could say Service Unavailable).
It is also important to note that the first time you deploy with WSPBuilder it does a true SharePoint install.
However, every subsequent time it does a SharePoint solution update. Solution updates work for most
ASP.NET Master Pages and SharePoint
Page 40 of 41
changes, however, there are some things it cant do. So, if you run into errors it is sometimes good to do
WSPBuilder Uninstall and then WSPBuilder-Deploy to do a real install in certain situations when you
are making changes.
If you are curious to what a SharePoint solution is doing, then just check out the files in the 12 hive:
C:\Program Files\Common Files\Microsoft Shared\web server extensions\12
You will notice that all the files we created in our Visual Studio solution have been pushed down to the
folders in the 12 hive. The WSP knows to push these files there. The WSP also knows to tell SharePoint
that these files exist. This is exactly how SharePoint develops its out of the box site definitions.
Side Notes:
1. Any file you place in the Layouts folder can be reference in the aspx pages as
/_layouts/{filename}. I usually recommend placing another folder under Layouts in the Visual
Studio solution (just because it makes it easy to find later - you can call this folder the name of
your company or the name of your project or anything that is obvious that it contains your custom
reference files). Then you can reference everything in there by /_layouts/{folder}/{filename}. An
example of this is css files in the master page. This is possible because SharePoint sets an IIS
path up to the Layouts folder in the 12 hive and calls it _layouts.
2. If you want to create a custom webpart with WSPBuilder just click Add new item WSPBuilder
WebPartFeature. This will create the feature folder, for your webpart, and the .cs class for your
webpart. This way you can go directly into coding and not have to worry about the Feature
creation. Once you are done coding the webpart just make sure it is in the appropriate scope of
your onet.xml file (SiteFeatures or WebFeatures) and it will become available to you in your
webpart gallery. Then all you have to do is worry about your dll being installed in the Bin or GAC.
If you choose GAC I recommend post-build scripts to move it.
3. Do not remove Content Place Holders from your master page if you start doing customizations.
The reason for this is if you assign other files in SharePoint (such as list pages) to use your
master pages, they will assume certain Content Place Holders exist. If they are not there, your
site will just break.
ASP.NET Master Pages and SharePoint
Page 41 of 41
You might also like
- Chapter5 Styles Master Pages and NavigationsNo ratings yetChapter5 Styles Master Pages and Navigations30 pages
- Chapter6 Styles Master Pages and NavigationsNo ratings yetChapter6 Styles Master Pages and Navigations30 pages
- Developing Web Applications Using Microsoft Visual Studio 2008No ratings yetDeveloping Web Applications Using Microsoft Visual Studio 200821 pages
- Unit-4 - ASP - Net and Web Development - Part-3No ratings yetUnit-4 - ASP - Net and Web Development - Part-337 pages
- WST Lecture 12 - Server Side Scripting - Consistent Look and Feel - Master Pages 07052025 125501pmNo ratings yetWST Lecture 12 - Server Side Scripting - Consistent Look and Feel - Master Pages 07052025 125501pm68 pages
- Investigacion Masterpage, ContentplaceholderNo ratings yetInvestigacion Masterpage, Contentplaceholder7 pages
- Progarmming in ASP - NET Theory AssignmentNo ratings yetProgarmming in ASP - NET Theory Assignment2 pages
- Master Pages:: Creating A Site-Wide Layout Using Master PagesNo ratings yetMaster Pages:: Creating A Site-Wide Layout Using Master Pages18 pages
- Master Page:: Source: Mindcracker NetworkNo ratings yetMaster Page:: Source: Mindcracker Network5 pages
- Mastering Node.js Web Development: Go on a comprehensive journey from the fundamentals to advanced web development with Node.jsFrom EverandMastering Node.js Web Development: Go on a comprehensive journey from the fundamentals to advanced web development with Node.jsNo ratings yet
- On-site SEO Guide: A 100% Practical Step By Step SEO Tutorial For Dummies & BeginnersFrom EverandOn-site SEO Guide: A 100% Practical Step By Step SEO Tutorial For Dummies & Beginners4/5 (3)
- HTML5,CSS3,Javascript and JQuery Mobile Programming: Beginning to End Cross-Platform App DesignFrom EverandHTML5,CSS3,Javascript and JQuery Mobile Programming: Beginning to End Cross-Platform App Design5/5 (3)
- Four Programming Languages Creating a Complete Website Scraper ApplicationFrom EverandFour Programming Languages Creating a Complete Website Scraper ApplicationNo ratings yet
- Spring Boot and Single-Page Applications: Securing Your API with a Single-Page Application Frontend - Second EditionFrom EverandSpring Boot and Single-Page Applications: Securing Your API with a Single-Page Application Frontend - Second EditionNo ratings yet
- Hypertext Markup Language (HTML) Fundamentals: How to Master HTML with EaseFrom EverandHypertext Markup Language (HTML) Fundamentals: How to Master HTML with EaseNo ratings yet
- ASP.NET For Beginners: The Simple Guide to Learning ASP.NET Web Programming Fast!From EverandASP.NET For Beginners: The Simple Guide to Learning ASP.NET Web Programming Fast!No ratings yet
