Building Block: Mobile Pages, Controls, and Adapters

Applies to: SharePoint Foundation 2010

This topic provides a brief overview of mobile pages, controls, and adapters as development building blocks in Microsoft SharePoint Foundation.

To make SharePoint Foundation deployments accessible to mobile devices, SharePoint Foundation provides a set of mobile pages and mobile controls that is entirely separate from the pages and controls that are accessed from (nonmobile) computers. Certain Web Parts are also made accessible to mobile devices by means of mobile Web Part adapters.

When a mobile device navigates to a SharePoint Foundation URL, SharePoint Foundation detects the browser type from the request header and redirects the request to a mobile version of the page. The mobile page will have mobile controls that generally mirror the functionality of controls on the nonmobile version of the page. If the nonmobile page is a Web Parts page, the mobile page may have adapters for one or more of the Web Parts on the nonmobile page. An adapter is an alternate version of the Web Part and its child controls that renders appropriately for the small screen of the mobile device.

You can create your own custom mobile pages, controls, and adapters to make your SharePoint Foundation solutions accessible from mobile devices.

Object Model for Mobile Pages, Controls, and Adapters

Classes for mobile development fall into three broad groups as discussed in the following subsections.

Mobile Page Classes

Mobile pages in SharePoint Foundation do not use master pages. Moreover, the distinction between site pages and application pages does not apply in SharePoint Foundation development for mobile devices. All mobile pages in SharePoint Foundation are application pages. They do not run in Safe Mode.

All SharePoint Foundation mobile pages inherit, directly or indirectly, from one or another of the following classes:

• SPMobilePage – Use this as a base class for your custom mobile page when none of the following more specific classes is applicable.

• SPMoblogPage – Use this as a base class for custom mobile pages that are a part of blog sites.

• WebPartMobilePage – Use this as a base class for custom mobile Web Parts pages. There must be a corresponding nonmobile WebPartPage object, called the target page, for every WebPartMobilePage object. Every Web Part on the target page for which a mobile adapter has been created is rendered on the mobile version of the page.

• SPMobileWikiPage – Use this class, which derives from WebPartMobilePage, as a base class for custom mobile wiki pages. For each page of this type, there must be a corresponding target wiki page. Every Web Part on the target page for which a mobile adapter has been created is rendered on the mobile version of the page.

In addition to creating your own mobile pages, you can modify the redirection system that routes requests from mobile devices to mobile pages. For more information, see Overview of Mobile Pages and the Redirection System, Mobile Pages, Layout and Pagination of Mobile Pages, and How to: Customize the Mobile Home Page Through Redirection. For more information about developing mobile pages in general, see also How to: Customize Mobile Home Pages, How to: Customize Mobile List View and Form Pages, and How to: Customize Field Rendering on Mobile Pages.

Mobile Control Classes

There are nearly 200 classes in the Microsoft.SharePoint.MobileControls namespace. They inherit ultimately from the Microsoft ASP.NET System.Web.UI.MobileControls.MobileControl class. With few exceptions, the inheritance parentage of a SharePoint Foundation mobile control includes SPMobileComponent. This class provides several kinds of members to SharePoint Foundation mobile controls, including the following:

• Members that provide SharePoint Foundation context information such as the current Web site, current list, the page type, and the current user’s permissions.

• Members that manage the truncation system that is used when a control is too large or has too many child elements to fit readably in the screen of a mobile device.

• Members that implement the rendering template system that renders controls.

Note

SPMobileComponent derives immediately from System.Web.UI.MobileControls.MobileControl, so no SharePoint Foundation class that derives from SPMobileComponent can derive from any specific Microsoft ASP.NET mobile control class, even when the name might lead you to think it does. For example, SPMobileListItem does not derive from System.Web.UI.MobileControls.MobileListItem. There are, however, some classes in the Microsoft.SharePoint.MobileControls namespace that do derive directly from corresponding ASP.NET classes and, thus, do not derive from SPMobileComponent. SPMobileLink is one example.

Most of the SharePoint Foundation mobile controls are not referenced directly in the mobile aspx pages. Instead, they are child objects of RenderingTemplate elements in the file MobileDefaultTemplates.ascx located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATES\ControlTemplates. The rendering template (which is an ASP.NET user control), is referenced, in turn, in the TemplateName property of an object that instantiates a class that is derived from SPMobileComponent. It is that last object that is referenced on the mobile page. Indeed, it is frequently the case that the rendering template that is referenced by the object on the page is itself only the first of a chain of rendering templates within MobileDefaultTemplates.ascx, each template referencing the next one, until the rendering template that actually contains the child mobile control is reached. In some cases, the control that is eventually rendered is selected dynamically based on contextual information such as the site type, page type, and list type.

In general, when you use custom controls in your SharePoint Foundation solution, you use this same system: add your custom controls to a custom rendering template in an ascx file in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATES\ControlTemplates, and then modify the calling system so that your custom rendering template is used where you want it on pages.

For more information about developing mobile controls, see Overview of Mobile Pages and the Redirection System, Mobile Page Rendering System, Ellipses and Rendering Limits, How to: Customize Mobile Home Pages, How to: Customize Mobile List View and Form Pages, How to: Customize Field Rendering on Mobile Pages, and the walkthrough topics in the Mobile Development How Tos and Walkthroughs node of the Microsoft SharePoint Foundation Software Development Kit (SDK).

Mobile Adapter Classes

SharePoint Foundation uses the ASP.NET system of control adapters to enable the functionality of Web Parts on mobile pages. All SharePoint Foundation mobile adapter classes derive from WebPartMobileAdapter which itself derives from the ASP.NET class ControlAdapter. The primary modifications that the WebPartMobileAdapter class makes to the ControlAdapterclass are changes that are designed to block direct access to the HTML writer object that renders the Web Part. These modifications are required for security.

Mobile Web Part adapters are not referenced on the mobile page. Instead, they are mapped to the Web Part they adapt in a configuration file. When the mobile page that corresponds to a target nonmobile Web Parts page renders, the runtime looks up each Web Part in the target page to see if it has an adapter. If it does, the adapter is rendered. If it does not, the Web Part is not rendered on the mobile page.

The following Web Part adapters are built-in to SharePoint Foundation:

• ImageWebPartMobileAdapter

• ListViewWebPartMobileAdapter

• XsltListViewWebPartMobileAdapter

You can create your own custom mobile Web Part adapters for either your custom Web Parts or for Web Parts that are built-in to SharePoint Foundation.

Even though mobile pages do not run in Safe Mode, you must register a Web Part adapter as a Safe Control just as a Web Part must be. This is to ensure that someone without editing rights to the web.config file cannot use a mobile page and a mobile adapter to access a Web Part that is not safe.

Note

SharePoint Foundation does not support creating mobile adapters for controls other than Web Parts.

For more information about developing mobile adapters for SharePoint Foundation, see How to: Create a Mobile Adapter and Walkthrough: Creating a Mobile Adapter.

Mobile Context Class

The SPMobileContext class is a convenience class that encapsulates properties about the current HTTP context that are especially useful when developing for mobile devices. For example, the MarkupLanguage property returns the name of the page rendering language used by the browser on the mobile device such as "html32", "chtml10", "xhtml-mp", or "wml11".

Mobile Redirection Members

The UnsecuredLayoutsPageBase class has virtual members that implement the system of redirecting requests from mobile devices to the mobile version of the requested page. If you derive a custom type of page from UnsecuredLayoutsPageBase (which would be a nonmobile page) and you want a mobile version of instances of the page accessible to mobile devices, but the default redirection logic is not appropriate for your page type, you can override these members.

Mobile Utilities Class

The SPMobileUtility class has dozens of static methods and fields for use in mobile development in SharePoint Foundation.

XML Used for Mobile Pages, Controls, Adapters, and Document Viewers

Most list views are not well designed for display on the small screen of a mobile device. For that reason, by default, only list views that have been designated as mobile views will display on a mobile page. (The converse is not the case. A mobile view can be seen on a nonmobile page.) There can also be a different default view of a list for mobile devices from the default view seen in computer browsers.

A list view is designated as a mobile view by setting the MobileView attribute of the View Element (List) element to True. You can designate a mobile view as the default mobile view by setting the MobileDefaultView attribute of the same element to True.

If your solution includes a viewer that enables documents of specified types to be viewed on mobile devices even if the format of the document is not the rendering format of the device’s browser, you can create a special mobile page that hosts the viewer and use XML markup to register the page and, optionally, let devices that contain their own viewers for the specified format open the document directly. For more information about this markup, see Developing Mobile Document Viewers.

Areas Related to Development of Mobile Pages, Controls, and Adapters

Building Block: Pages and User Interface

Building Block: Web Parts

More Information about Development of Mobile Pages, Controls, and Adapters

Extensive and detailed information about SharePoint Foundation development for mobile devices is in the node named Mobile Development with SharePoint Foundation in this SDK.