Creating a Custom SharePoint MasterPage using a Feature

Creating a custom MasterPage is a very common requirement especially for those who want to migrate from ASP.NET 2.0 to SharePoint, without altering the look and feel they already had previously.

I have searched a lot about how to accomplish this, and found many articles and blog posts but they are all incomplete, they are missing the complete guide. I will try to be as direct as possible, and include screen shots that I hope they would help.

Anyway, lets start and get our hands dirty...

1. Navigate to the following folder: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\
   Copy the PageLayouts folder and paste it in the same directory but Change the folder name to another one. To easily follow up with me through this post, lets call it CustomMasterPages.
   
   
   
   Add the masterpage you want in the masterpage folder, the CSS file into the styles folder, and all images you need into the images folder.
   
2. Open the CustomMasterPages folder. Now we have to Edit the Feature.xml that has the main Registry info about the new feature you want to create (in our case, the custom MasterPage). So open the feature.xml file using your favorite text editor.
   Delete what the file has, and paste the following:

   
   
   77596cae-c12d-4451-9d65-53b66b2fd5aa"
   Title="CS Masterpage"
   Description="My own Custom MasterPage"
   Version="12.0.0.0"
   Scope="Site"
   Hidden="False"
   DefaultResourceFile="core"
   xmlns="http://schemas.microsoft.com/sharepoint/">
   
   
   
   

   You have to change only the following fields, but I advice you to leave everything as it is for this Demo, just as a good kick off :)
   ID: A GUID to identify the feature. you can go to http://www.newguid.com/ to generate a new GUID (you will find it in the upper banner) and paste it right there.
   Title: the Feature name (Custom MasterPage name).
   Description: Feature's description.
   The Element Manifest is considered as the backbone of the feature; you have to specify its location, which is by default named as ProvisionedFiles.xml located at the same level with the feature.xml. Save the file and close it.

3. Now open the ProvisionedFiles.xml file and let's see what we have got there.
   You simply link EVERYTHING you have in the CustomMasterPages folder, and create an entry for it in the ProvisionedFiles.xml

   
   
   http://schemas.microsoft.com/sharepoint/">
   
   MasterPage.master" Type="GhostableInLibrary">
   
   
   
   
   This is my sample master page for use with collaboration or publishing sites." />
   
   
   
   
   
   
   
   
   
   1_Duane.jpg" Name="1_Duane.jpg" Type="GhostableInLibrary"/>
   
   
   CS MasterPage.css" Type="GhostableInLibrary" />
   

   Now we are done with the 2 most important pages.

4. One important thing you must take care of, is that the masterpage design is not the same as what you used to do in ASP.NET 2.0. Its not an HTML page with some ContentPlaceHolders with random IDs and placed anywhere like before. SharePoint's MasterPages are way different; there are a number of predefined ContentPlaceHolders with specific ids (you can't change them, or they wont be recognized, and the MOSS will hit you with a silly frustrating error page!). These ContentPlaceHolders are recognized by the MOSS according to their IDs. Have a look at the complete list below:
   
   
   
   yet, you dont have to place ALL of these ContentPlaceHolders into your new customized MasterPage. there are some of these which are essential, and others not. The following is a minimal MasterPage that you cant remove anything from it, or it wont work at all. You can always use it as a start for designing your masterpages.. i.e NEVER START THE MASTERPAGE DESIGN FROM SCRATCH! or you will end up banging your head against the wall!

   <%-- Identifies this page as a .master page written in Microsoft Visual C# and registers tag prefixes, namespaces, assemblies, and controls. --%>
   <%@ Master language="C#" %>
   http://www.w3.org/TR/html4/loose.dtd">
   <%@ Import Namespace="Microsoft.SharePoint" %>
   <%@ Register Tagprefix="SPSWC" Namespace="Microsoft.SharePoint.Portal.WebControls" Assembly="Microsoft.SharePoint.Portal, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
   <%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
   <%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
   <%@ Register Tagprefix="PublishingWebControls" Namespace="Microsoft.SharePoint.Publishing.WebControls" Assembly="Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
   <%@ Register Tagprefix="PublishingNavigation" Namespace="Microsoft.SharePoint.Publishing.Navigation" Assembly="Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
   <%@ Register TagPrefix="wssuc" TagName="Welcome" src="~/_controltemplates/Welcome.ascx" %>
   <%@ Register TagPrefix="wssuc" TagName="DesignModeConsole" src="~/_controltemplates/DesignModeConsole.ascx" %>
   <%@ Register TagPrefix="PublishingVariations" TagName="VariationsLabelMenu" src="~/_controltemplates/VariationsLabelMenu.ascx" %>
   <%@ Register Tagprefix="PublishingConsole" TagName="Console" src="~/_controltemplates/PublishingConsole.ascx" %>
   <%@ Register TagPrefix="PublishingSiteAction" TagName="SiteActionMenu" src="~/_controltemplates/PublishingActionMenu.ascx" %>
   <%-- Uses the Microsoft Office namespace and schema. --%>
   
   
   <%-- The head section includes a content placeholder for the page title and links to CSS and ECMAScript (JScript, JavaScript) files that run on the server. --%>
   
   
   
   
   
   
   
   <%-- When loading the body of the .master page, SharePoint Server 2007 also loads the SpBodyOnLoadWrapper class. This class handles .js calls for the master page. --%>
   
   <%-- The SPWebPartManager manages all of the Web part controls, functionality, and events that occur on a Web page. --%>
   

   
   
   
   
   
   
   <%-- The PlaceHolderMain content placeholder defines where to place the page content for all the content from the page layout. The page layout can overwrite any content placeholder from the master page. Example: The PlaceHolderLeftNavBar can overwrite the left navigation bar. --%>
   
   
   <%-- These ContentPlaceHolders ensure all default SharePoint Server pages render with this master page. If the system master page is set to any default master page, the only content placeholders required are those that are overridden by your page layouts. --%>
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   

   So to start, you can get whatever HTML you have in the old MasterPage and paste it in here, just below the . Then arrange the ContentPlaceHolders wherever you want into your HTML code.
   Another point you must take care of; the images and background's source urls. of course, we added the images previously into the CustomMasterPages\images folder, so we will replace the old source urls you had in the html code into something like:
   background="/Style%20Library/images/bg1.jpg">
   and for sure, that would be the same case in the CSS file.

5. Now we are ready to install the feature!
   open the command prompt (Start> Run), then type:
   cd C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN
   Now type the following
   stsadm -o installfeature -filename CustomMasterPages\feature.xml
   We are installing the feature that we are providing its feature.xml file (the xml file's path from the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES folder).
   
6. Activate the feature for your site.
   open the Internet Browser, and type in the webapplication's URL.. something like http://ahmed-ig:35193 and concatenate /_layouts/settings.aspx to the previous part.
   i.e: http://ahmed-ig:35193/_layouts/settings.aspx
   
   under the "Site Collection Administration" column, click on "Site collection features"
   
   
   
   locate the Feature you have just made. (you will find its name as you named it in the feature.xml file)
   
   
   
   Now Press on the Activate Button to activate the Feature.
   
   
7. Apply the MasterPage into your site
   Now get back to the url you opened in Step #7
   and under the "Look and Feel" column, click on "Master page".
   Choose the Site Master Page as the customized MasterPage you have created.
   and leave the System Master Page as it is.
   Now you have to upload the CSS file you are using in your customized MasterPage file.
   
   
   

And Hopefully, that's it! Hope it works smoothly without any problems :)