How to: Customize the Mobile Home Page Through Redirection

Applies to: SharePoint Foundation 2010

As described in Home Page Redirection, Microsoft SharePoint Foundation has a second system of redirection for home pages only. This topic explains how you can modify this system to cause mobile users to see an alternative home page for a specific site type.

Home Page Redirection uses a bi-level redirection mechanism. Mobile devices are initially redirected to the mobile default.aspx page that is located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS\MOBILE. The default.aspx page then redirects the user to the actual home page, according to the current site definition type, using the following sequence:

1. The only content in default.aspx is a control that tells the runtime to use a RenderingTemplate called MobileHomePageRedirect.

2. The runtime searches memory for all the rendering controls loaded from .ascx files in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\CONTROLTEMPLATES for a RenderingTemplate that has this name. It finds one from the MobileDefaultTemplates.ascx file.

3. The Template property of the MobileHomePageRedirect control points the runtime to an object of the SPMobileWebUrlRedirect class.

4. The SPMobileWebUrlRedirect object constructs the name of another RenderingTemplate using the pattern Mobile_SiteTypeID_HomePage_Redirect, where SiteTypeID is either the name of a site definition that is included with SharePoint Foundation, such as STS, SGS, or BLOG; or the ID number of a custom site definition, such as 10001. (For more information, see the reference topic for the SPMobileWebUrlRedirect class.)

5. The runtime searches all the rendering templates loaded from .ascx files in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\CONTROLTEMPLATES for this second RenderingTemplate.

   • If SiteTypeID is BLOG, the runtime will find the Mobile_BLOG_HomePage_Redirect RenderingTemplate in MobileDefaultTemplates.ascx. The latter control's Template property points the runtime to an object of the SPMobileHomePageRedirection class, whose PageFileName property specifies that bloghome.aspx is the home page.

   • If SiteTypeID is not BLOG, and no custom .ascx files have been created, the runtime uses the Mobile_Default_HomePage_Redirect RenderingTemplate in MobileDefaultTemplates.ascx. The latter control's Template property points the runtime to an object of the SPMobileHomePageRedirection class, whose PageFileName property specifies that mblwp.aspx is the home page.

You can create a custom control that redirects users to an alternative mobile home page.

Procedures

To replace the mobile home page through redirection

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\LAYOUTS\MOBILE.

3. Right-click the new folder, add a plain text file to be your new home page, and give it a name with an .aspx extension; for example, ContosoHomePage.aspx. 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\LAYOUTS\MOBILE.

   Tip

   Do not add a SharePoint Application Page item to the project. Visual Studio includes with such items some deployment overhead folders and files (and default content to the file) that are not appropriate for a mobile page.

4. Copy the contents of an existing page from %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS\MOBILE—such as mblwiki.aspx, mblwp.aspx, mblwpdetail.aspx, or bloghome.aspx—into your custom file.

5. Modify the contents of the file as needed. (For a quick test, copy the contents of mblwiki.aspx, and then swap the foreground and background color settings in the header so that the page title will be dark blue-gray type on a white background instead of the default white type on a dark blue-gray background.)

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

7. Right-click the new folder, and add a User Control to the folder. Give the .ascx file a name that will distinguish it from the names of other solution providers; for example, ContosoHomePageRedirection.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 and, if it is not moved, 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.

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

9. 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" %>
   

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

    SiteTypeID can be any of the following:

    • The name of the team site definition: "STS"

    • The name of the group work site definition "SGS"

    • The ID number (not the name) of any custom site definition that has been created.

    There is already a Mobile_BLOG_HomePage_Redirect RenderingTemplate defined in MobileDefaultTemplates.ascx. You may not modify this file. You can create a second RenderingTemplate, also named Mobile_BLOG_HomePage_Redirect, in a custom .ascx file, but doing this risks breaking other installed custom or third-party solutions that may depend on the existing Mobile_BLOG_HomePage_Redirect.

    The RenderingTemplates that are included with SharePoint Foundation load first, so the standard rendering template is overwritten when a custom template of the same name is loaded. If two or more custom RenderingTemplates have the same name, the template whose file name is alphabetically last will override the other templates. If a given file has two or more templates that have the same name, none of them is loaded.

    Note

    The MPS, CENTRALADMIN, TENANTADMIN, and legacy WIKI site definitions do not support access from mobile devices.

    Note

    The name of a site definition is defined by the Name attribute of a Template element in a WebTemp.xml file, and the ID of the site definition is set with the ID attribute of the same element. For more information about these attributes, see WebTemp.xml.

    Important

    The site definition configuration’sConfiguration element in the site definition's Onet.xml file must have a WebFeatures element, and that element must have the Home Page Redirection feature element: <Feature ID="F41CC668-37E5-4743-B4A8-74D1DB3FD8A4" />.

    The following shows an example of a template that redirects mobile devices that access websites based on the STS site definition to ContosoHomePage.aspx.

    <SharePoint:RenderingTemplate RunAt="Server"
       ID="Mobile_STS_HomePage_Redirect">
      <Template>
        <SPMobile:SPMobileHomePageRedirection RunAt="Server" 
          PageFileName="ContosoHomePage.aspx" />
      </Template>
    </SharePoint:RenderingTemplate>
    

11. On the Build menu, select Deploy Solution. This automatically saves the .ascx file, deploys the two files, and recycles the web application so that all the .ascx files in that folder are reloaded.

12. Test your new home page using a mobile device or emulator. Notice that whether you see your alternate home page or the original depends on exactly the URL that you use. See earlier in this topic for more information.

See Also

Concepts

Mobile Development with SharePoint Foundation

Other Resources

Mobile Development How Tos and Walkthroughs