Master Pages and SharePoint
Master Pages and SharePoint
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
Master Page
Content Page
Re
su
ltin
gP
ag
Page 1 of 41
<%@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
</ContentPlaceHolder>
Re
su
ltin
gP
ag
<%@Master language="C#"%>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
ASP.NET Master Pages and SharePoint
Page 2 of 41
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.
Page 3 of 41
Master Page
Content Page
</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.
LOGO
TOP Menu
Side Menu
ContentPlaceHolder1
ContentPlaceHolder2
ContentPlaceHolder3
Page 4 of 41
Page 5 of 41
Page 6 of 41
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
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.
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.
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.
Page 12 of 41
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:
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.
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
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.
Page 16 of 41
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).
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.
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.
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."
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.
Page 19 of 41
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.
Page 20 of 41
Page 21 of 41
Page 22 of 41
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
Page 23 of 41
Page 24 of 41
Page 25 of 41
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.
Page 26 of 41
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.
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
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:
-
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.
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.
Page 31 of 41
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.
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.
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
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.
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
-
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
Page 35 of 41
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.
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.
-
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>
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>
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
-
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.
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>
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.
Page 39 of 41
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.
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.
Page 41 of 41