Upgrading an Existing Master Page to the SharePoint Foundation Master Page

Applies to: SharePoint Foundation 2010

There have been significant changes to the user interface (UI) for Microsoft SharePoint Foundation 2010, including the addition of the Server ribbon. By default, the v4.master page includes the Server ribbon. Many of the commands previously found in menus and toolbars now exist inside of the Server ribbon. As a result, if your existing master page does not contain the Server ribbon, many commands will be unavailable. This topic shows you how to add the Server 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 Server Ribbon

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

• Publishing Console - <PublishingConsole:Console>

• Site Actions Menu - <PublishingSiteAction:SiteActionMenu>

• Sign-in and Log-in Control

Important

If you are using a custom sign-in control, you can move the control inside or outside of the Server ribbon, based on your layout.

Add Content Placeholders

You must ensure that the new ContentPlaceHolder controls exist in order to update your master page to be compatible with SharePoint Foundation 2010. The following table lists all of the placeholders required for update your master page to be compatible with SharePoint Foundation 2010.

Important

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, which appears in the title area on 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 breadcrumb control on the page.	No
<asp:ContentPlaceHolder id="PlaceHolderTitleBreadcrumb" runat="server">	The breadcrumb text for the breadcrumb control.	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 container used to hold the top navigation bar.	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 additional objects above 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 Server Ribbon

The Server 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 Server ribbon area. This content can be moved outside of the Server ribbon if desired. The following procedure shows the code for adding the Server ribbon to the page.

To add the Server Ribbon

1. Open your master page file (.master).

2. Copy and paste the following code inside the form tag to add the Server ribbon to the page.

   Important

   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 Server ribbon.

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

3. Save your master page file.

Maintain the Position of the Server Ribbon While Scrolling

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

To maintain the position of the Server ribbon while scrolling

1. Move the content of your site inside the following div elements.

   Important

   The s4-workspace div element is required in editing scenarios. A script error will occur if this element does not exist.

   <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 s4-workspace div element. The updated div element would look like the following. <div id="s4-workspace" class="s4-nosetwidth">

2. Move the title area of your site into a div element with the following ID.

   <div id="s4-titlerow"> 
     Title Area
   </div>
   

3. Update the body tag and Cascading Style Sheet (CSS) rule to not scroll. The body tag and rule would look similar to the following.

   <body scroll="no" ...>
     Body Content
   </body>
   

   body { overflow: hidden; ... }
   

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 and from the Server 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 JavaScript in SharePoint Foundation, you must have an instance of the ScriptManager on the page.

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

To add the controls to the page

1. Open your master page file.

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

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

3. Copy and paste the following code to add the SPPageManager control to the page. This must be within the head tag.

   <SharePoint:SPPageManager runat="server" />
   

4. Copy and paste the following code to add the ScriptLink control to the page. This must be within the head tag.

   <SharePoint:ScriptLink defer= "true" runat="server"/>
   

5. Save your master page file.

See Also

Concepts

Master Pages