Upgrading an Existing Master Page to the SharePoint Foundation Master Page

[This documentation is preliminary and is subject to change.]

There have been significant changes to the user interface (UI) for Microsoft SharePoint Foundation 2010, including the addition of the Ribbon. By default, the v4.master page includes the Ribbon. Many of the commands previously found in menus and toolbars now exist inside of the Ribbon. As a result, if your existing master page does not contain the Ribbon, many commands will be unavailable. This topic shows you how to add the Ribbon along with any new controls or content placeholders that are required for an existing master page to render correctly in SharePoint Foundation 2010.

Prerequisites

Microsoft SharePoint Foundation 2010

Controls on the Ribbon

There are some controls that were previously included with the default master page that have been moved into the new Ribbon UI. Because these controls now exist inside the Ribbon, if you plan to update an existing master page with Ribbon functionality, you need to remove the following controls from your existing master page. These controls will be added when your incorporate the Ribbon into your master page.

Publishing Console - <PublishingConsole:Console>
Site Actions Menu - <PublishingSiteAction:SiteActionMenu>
Sign-in and Log-in Control

Important Note:
If you are using a custom sign-in control, you can move the control inside or outside of the Ribbon, based on your layout.

Add Content Placeholders

You must ensure that the new ContentPlaceholder controls exist in order to upgrade to the SharePoint Foundation 2010 master page. The following table lists all of the placeholders required for the page to operate.

Important Note:
The PlaceHolderTitleAreaClass placeholder is now in the head tag. Any customizations that add a WebPartZone in a content tag to this placeholder will cause an error on the page.

Placeholder Control	Description	New
<asp:ContentPlaceHolder id="PlaceHolderQuickLaunchTop" runat="server">	The top of the Quick Launch menu.	Yes
<asp:ContentPlaceHolder id="PlaceHolderQuickLaunchBottom" runat="server">	The bottom of the Quick Launch menu.	Yes
<asp:ContentPlaceHolder id="PlaceHolderPageTitle" runat="server"/>	The title of the site.	No
<asp:ContentPlaceHolder id="PlaceHolderAdditionalPageHead" runat="server"/>	A placeholder in the head section of the page used to add extra components such as ECMAScript (JavaScript, JScript) and Cascading Style Sheets (CSS) to the page.	No
<asp:ContentPlaceHolder id="PlaceHolderBodyAreaClass" runat="server"/>	The class of the body area.	No
<asp:ContentPlaceHolder ID="SPNavigation" runat="server">	A control used for additional page editing controls.	No
<asp:ContentPlaceHolder id="PlaceHolderSiteName" runat="server">	The name of the site where the current page resides.	No
<asp:ContentPlaceHolder id="PlaceHolderPageTitleInTitleArea" runat="server" />	The title of the page.	No
<asp:ContentPlaceHolder id="PlaceHolderPageDescription" runat="server"/>	The description of the current page.	No
<asp:ContentPlaceHolder id="PlaceHolderSearchArea" runat="server">	The section of the page for the search controls.	No
<asp:ContentPlaceHolder id="PlaceHolderGlobalNavigation" runat="server">	The global navigation on the page.	No
<asp:ContentPlaceHolder id="PlaceHolderTitleBreadcrumb" runat="server">	The top navigation bar in the main page content area.	No
<asp:ContentPlaceHolder id="PlaceHolderGlobalNavigationSiteMap" runat="server">	The list of subsites and sibling sites in the global navigation on the page.	No
<asp:ContentPlaceHolder id="PlaceHolderTopNavBar" runat="server">	The top navigation where GlobalNavigationSiteMap is contained.	No
<asp:ContentPlaceHolder id="PlaceHolderHorizontalNav" runat="server">	The navigation menu that is inside the top navigation bar.	No
<asp:ContentPlaceHolder id="PlaceHolderLeftNavBarDataSource" runat="server" />	The placement of the data source used to populate the left navigation bar.	No
<asp:ContentPlaceHolder id="PlaceHolderCalendarNavigator" runat="server" />	The date picker used when a calendar is visible on the page.	No
<asp:ContentPlaceHolder id="PlaceHolderLeftNavBarTop" runat="server"/>	The top section of the left navigation bar.	No
<asp:ContentPlaceHolder id="PlaceHolderLeftNavBar" runat="server">	The Quick Launch bar.	No
<asp:ContentPlaceHolder id="PlaceHolderLeftActions" runat="server">	The menu used to contain objects in the Quick Launch bar.	No
<asp:ContentPlaceHolder id="PlaceHolderMain" runat="server">	The main content of the page.	No
<asp:ContentPlaceHolder id="PlaceHolderFormDigest" runat="server">	The container where the page form digest control is stored.	No
<asp:ContentPlaceHolder id="PlaceHolderUtilityContent" runat="server"/>	The additional content at the bottom of the page. This is outside of the form tag.	No
<asp:ContentPlaceHolder id="PlaceHolderTitleAreaClass" runat="server"/>	The class for the title area. This is now in the head tag. Any customizations that add a WebPartZone in a content tag to this placeholder will cause an error on the page.	No
<asp:ContentPlaceHolder id="PlaceHolderPageImage" runat="server"/>	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No
<asp:ContentPlaceHolder id="PlaceHolderTitleLeftBorder" runat="server">	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No
<asp:ContentPlaceHolder id="PlaceHolderMiniConsole" runat="server"/>	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No
<asp:ContentPlaceHolder id="PlaceHolderTitleRightMargin" runat="server"/>	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No
<asp:ContentPlaceHolder id="PlaceHolderTitleAreaSeparator" runat="server"/>	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No
<asp:ContentPlaceHolder id="PlaceHolderNavSpacer" runat="server">	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No
<asp:ContentPlaceHolder id="PlaceHolderLeftNavBarBorder" runat="server">	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No
<asp:ContentPlaceHolder id="PlaceHolderBodyLeftBorder" runat="server">	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No
<asp:ContentPlaceHolder id="PlaceHolderBodyRightMargin" runat="server">	This placeholder does not appear as part of the UI and must be present for backward compatibility.	No

Add the Ribbon

The Ribbon is a new addition to the UI for SharePoint Foundation. The SPRibbonPeripheralContent controls in the v4.master page contain content that renders inside the Ribbon area. This content can be moved outside of the Ribbon if desired. The following procedure shows the code for adding the Ribbon to the page.

To add the Ribbon

Open your master page file (.master).

Copy and paste the following code inside the form tag to add the Ribbon to the page.

Important Note:
The following code sample contains commented sections where you copy and paste controls from your custom master page or from the v4.master page. Any ContentPlaceholder controls inside the Global Navigation section need to be added to the page elsewhere if you do not add them within the Ribbon.

HTML

<div id="s4-ribbonrow" class="s4-pr s4-ribbonrowhidetitle">
  <div id="s4-ribboncont">
    <SharePoint:SPRibbon
     runat="server"
     PlaceholderElementId="RibbonContainer"
     CssFile="">
      <SharePoint:SPRibbonPeripheralContent
  runat="server"
  Location="TabRowLeft"
  CssClass="ms-siteactionscontainer s4-notdlg">
     <%-- Insert the Site Actions Menu Here --%>
     </SharePoint:SPRibbonPeripheralContent>

     <%-- Insert the Global Navigation Here --%>
     <SharePoint:SPRibbonPeripheralContent
       runat="server"
       Location="TabRowRight"
       ID="RibbonTabRowRight"
       CssClass="s4-trc-container s4-notdlg">
     <%-- Insert the Top-Right Corner Controls Here --%>
     </SharePoint:SPRibbonPeripheralContent>

    </SharePoint:SPRibbon>
  </div>
  <div id="notificationArea" class="s4-noti">
    <%-- Notifications will appear in this div element. --%> 
  </div>
  <asp:ContentPlaceHolder ID="SPNavigation" runat="server">
    <SharePoint:DelegateControl runat="server" ControlId="PublishingConsole">
    </SharePoint:DelegateControl>
  </asp:ContentPlaceHolder>
  <div id="WebPartAdderUpdatePanelContainer">
    <asp:UpdatePanel
     ID="WebPartAdderUpdatePanel"
     UpdateMode="Conditional"
     ChildrenAsTriggers="false"
     runat="server">
        <ContentTemplate>
          <WebPartPages:WebPartAdder ID="WebPartAdder" runat="server" />
        </ContentTemplate>
        <Triggers>
          <asp:PostBackTrigger ControlID="WebPartAdder" />
        </Triggers>
    </asp:UpdatePanel>
  </div>
</div>

Save your master page file.

Prevent the Ribbon from Scrolling with the Page

When adding the Ribbon, make the following changes to the master page to prevent the Ribbon from scrolling with the page.

To prevent Ribbon scrolling

Move the content of your site inside the following div elements.
HTML
```
<div ID="s4-workspace">
  <div ID="s4-bodyContainer">
    Content
  </div>
</div>
```
Note:
If your page is fixed width, add the class s4-nosetwidth to the bodyContainer div element. The updated div element would look like the following. <div ID="s4-bodyContainer" class="s4-nosetwidth">
Move the title area of your site into a div element with the following ID.
HTML
```
<div ID="s4-titlerow"> 
  Title Area
</div>
```
Update the body tag and Cascading Style Sheet (CSS) selector to not scroll. The body tag and selector would look similar to the following.
HTML
```
<body scroll="no" ...>
  Body Content
</body>
```
```
body { overflow: hidden; ... }
```

Note:
If your page is fixed width, add the class s4-nosetwidth to the bodyContainer div element. The updated div element would look like the following. <div ID="s4-bodyContainer" class="s4-nosetwidth">

Add Controls to the Master Page

There are a set of controls that are required for SharePoint Foundation to function. These are the SPPageManager, ScriptManager, and ScriptLink controls.

The SPPageManager control manages communications on the page. This control takes care of routing commands to the Ribbon, toolbars, and other controls on the page.

The ScriptManager object is a Microsoft ASP.NET control that is used to manage all of the ECMAScript (JavaScript, JScript) on the page. Due to the extensive use of ECMAScript in SharePoint Foundation, you must have an instance of the ScriptManager on the page.

The ScriptLink control is necessary to handle adding references to ECMAScript on the page. This control renders a link to the ECMAScript on the page.

To add the controls to the page

Open your master page file.

Copy and paste the following code to add the ScriptManager control to the page. This must be within the form tag but before the Ribbon.

HTML

<asp:ScriptManager id="ScriptManager" runat="server" EnablePageMethods="false" EnablePartialRendering="true" EnableScriptGlobalization="false" EnableScriptLocalization="true" />

Copy and paste the following code to add the SPPageManager control to the page. This must be within the head tag.
HTML
```
<SharePoint:SPPageManager runat="server" />
```
Copy and paste the following code to add the ScriptLink control to the page. This must be within the head tag.
HTML
```
<SharePoint:ScriptLink defer= "true" runat="server"/>
```
Save your master page file.

Concepts

Master Pages