How to: Customize Mobile Home Pages

  • Article

Applies to: SharePoint Foundation 2010

This topic provides an overview of the basic procedure for customizing a Microsoft SharePoint Foundation home page that can be accessed by mobile devices. For a detailed procedure, see Walkthrough: Customizing a Mobile Home Page. For an overview of how to customize list view and form pages, see How to: Customize Mobile List View and Form Pages.

As described in detail in Mobile Page Rendering System, controls in the Header (Title), Body (Contents), and Footer (Navigation) areas of a mobile home page each start a chain of calls that ultimately results in a call to a RenderingTemplate object that renders the corresponding area of the mobile page. This is almost always a RenderingTemplate with a segmented ID. If a RenderingTemplate with a matching name is not found, a default template is used. This means that you can customize the Header, Body, or Footer, by creating a RenderingTemplate with the ID for which the runtime will be looking.

Specifically, the runtime will be looking for a RenderingTemplate ID that has the following format:

IntendedPageUse_SiteTypeID_HomePage_PageArea

The placeholders IntendedPageUse, SiteTypeID, and PageArea, are defined in Segmented Rendering Template IDs. For more information about the sections of a mobile page, see Layout and Pagination of Mobile Pages.

For a specific IntendedPageUse, SiteTypeID, and PageArea, if a RenderingTemplate with a matching name is not found, one with "Default" in place of the SiteTypeID is used:

IntendedPageUse_Default_HomePage_PageArea

For example, if the runtime is looking for a RenderingTemplate with the ID WebPartMobile_STS_HomePage_Title, it will not find one (if no custom template with that name has been added). So it will use WebPartMobile_Default_HomePage_Title, which does exist, to render the Header (Title) area of the mobile home page for an STS site.

So if you wanted to customize the rendering of the Header of the mobile home page for an STS site, you could do it by creating a RenderingTemplate element with the ID WebPartMobile_STS_HomePage_Title in an .ascx file that you deploy to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATES\ControlTemplates. You may not modify the MobileDefaultTemplates.ascx or GbwMobileDefaultTemplates.ascx files. For more information about how to create a custom rendering template for a mobile page, see the procedure later in this topic, and also Walkthrough: Customizing a Mobile Home Page.

Existing RenderingTemplates

The following list contains the RenderingTemplates for mobile home pages that already exist in MobileDefaultTemplates.ascx or GbwMobileDefaultTemplates.ascx when SharePoint Foundation is installed.

  • Mobile_STS_HomePage_Title

  • Mobile_STS_HomePage_Contents

  • WebPartMobile_SGS_HomePage_Contents

  • WebPartMobile_STS_HomePage_Contents

You can create a new RenderingTemplate element (in your own .ascx file) using the same ID as one of these existing rendering templates. However, if you do, there is a risk that you will break other solutions that are deployed in SharePoint Foundation that depend on the original RenderingTemplate object.

Note

The rendering templates that are included with SharePoint Foundation load before custom templates load. Therefore, when a custom template with the same ID as one of the existing rendering templates loads, it overrides the original template. If two or more custom rendering templates have the same ID, the template whose file name is alphabetically last will override all the other templates. If a specific file has two or more rendering templates that have the same ID, none of them is loaded.

The following RenderingTemplate objects are also defined in the MobileDefaultTemplates.ascx or GbwMobileDefaultTemplates.ascx files. These are used by the runtime whenever a RenderingTemplate object for the current site type is not defined. (Therefore, these templates control home page rendering of any pages in a website that is based on a custom site definition, unless a custom rendering template with the ID IntendedPageUse_ CustomSiteID#_HomePage_PageArea is created.) The same risk is present if you create a new RenderingTemplate object with any of these IDs.

  • Mobile_Default_HomePage_Title

  • Mobile_Default_HomePage_Contents

  • Mobile_Default_HomePage_Navigation

  • WebPartMobile_Default_HomePage_Title

  • WebPartMobile_Default_HomePage_Contents

  • WebPartMobile_Default_HomePage_Navigation

  • WebPartMobileDetail_Default_HomePage_Contents

  • WebPartMobileDetail_Default_HomePage_Navigation

You can nest RenderingTemplate objects. See the example in the next section.

To customize a section of a mobile home page

  1. In Microsoft Visual Studio, create an Empty SharePoint Project. Make it a farm solution, not a sandboxed solution.

  2. Add a SharePoint Mapped Folder to TEMPLATE\ControlTemplates.

  3. Right-click the new folder, and add a SharePoint User Control. Give the .ascx file a name that will distinguish it from those of other solution providers; for example, ContosoMobileRenderingTemplates.ascx. Visual Studio automatically adds the file to the SharePoint Solution manifest and sets it to be deployed to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\ControlTemplates.

    Tip

    Do not add the User Control by right-clicking the project in Solution Explorer. When you add a User Control in this manner, Visual Studio puts it in a subfolder of TEMPLATE\ControlTemplates. If it is not moved, Visual Studio deploys it to a corresponding subfolder of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\ControlTemplates. Mobile rendering templates in subfolders are not loaded.

  4. Delete the .ascx.cs and .ascx.designer.cs (or .ascx.vb and .ascx.designer.vb) files. They are not needed for this project.

  5. Replace the entire directives section of the .ascx file with the following markup:

    <%@ Register TagPrefix="GroupBoardMobile"   Namespace="Microsoft.SharePoint.Applications.GroupBoard.MobileControls" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Control Language="C#"   %> 
<%@ Assembly Name="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> 
<%@ Register TagPrefix="mobile" Namespace="System.Web.UI.MobileControls" Assembly="System.Web.Mobile, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" %> 
<%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> 
<%@ Register TagPrefix="SPMobile" Namespace="Microsoft.SharePoint.MobileControls" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> 
<%@ Register TagPrefix="WPMobile" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

  6. Add a rendering template to the .ascx file, and give it an ID in the following format: IntendedPageUse_SiteTypeID_HomePage_PageArea.

    • IntendedPageUse is Mobile, WebPartMobile, or WebPartMobileDetail.

    • SiteTypeID can be STS, SGS, BLOG, or the ID number (not the name) of any custom site definition. (The ID of a site definition is set with the ID attribute of a Template element in a WebTemp.xml file. For more information about the ID attribute of a site definition, see WebTemp.xml.)

    • PageArea can be Title, Contents, or Navigation.

  7. On the Build menu, select Deploy Solution. This automatically saves the .ascx file, deploys it to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATES\ControlTemplates, and recycles the web application, so that all the .ascx files in that folder are reloaded.

Example

The following example of a RenderingTemplate definition shows how you can nest RenderingTemplates. In this case, the custom template adds a link to Microsoft’s mobile page to the footer and then calls the default footer rendering template to render the rest of the footer.

If the mobile device is not capable of rendering Rich Text, the mobile STS home page is mblwp.aspx, and the user will see the new link added to the top of the footer.

If the device is capable of rendering Rich Text, the mobile STS home page is mblwiki.aspx. The control in the Footer (Navigation) area of this page does not call any rendering template with a segmented name, not even indirectly. In particular, WebPartMobile_STS_HomePage_Navigation is not called. For that reason, the Footer of mblwiki.aspx cannot be customized in the manner described in this topic. Accordingly, the customization that is described in this example initially appears to have no effect on mobile devices that are capable of rendering Rich Text. You can force such a device to use mblwp.aspx as the home page by replacing (in the address box of the mobile browser) the "wiki" in mblwiki.aspx with "wp". The Header (Title) and Body (Contents) areas of mblwiki.aspx use the same rendering templates as do the corresponding areas in mblwp.aspx, so you can use the procedure in this topic to customize the Header and Body areas for both devices which can, and devices which cannot, render Rich Text.

For another example of customizing a mobile home page, see Walkthrough: Customizing a Mobile Home Page.

<SharePoint:RenderingTemplate ID="WebPartMobile_STS_HomePage_Navigation" RunAt="Server">
  <Template>
    <mobile:Link Text="Microsoft Mobile" href="http://mobile.microsoft.com/" RunAt="Server" />
    <SPMobile:SPMobileComponent TemplateName="WebPartMobile_Default_HomePage_Navigation" RunAt="Server" />
  </Template>
</SharePoint:RenderingTemplate>

See Also

Tasks

Walkthrough: Customizing a Mobile Home Page

How to: Customize Mobile List View and Form Pages

Concepts

Layout and Pagination of Mobile Pages

How to: Customize the Mobile Home Page Through Redirection

Mobile Page Rendering System