Mobile Page Rendering System

Applies to: SharePoint Foundation 2010

This topic describes how Microsoft SharePoint Foundation uses RenderingTemplate controls and template selector controls to render pages that can be accessed from mobile devices.

Controls on the Page

Mobile pages are rendered with RenderingTemplate controls, but these controls are not directly called from the page. Instead, an SPMobileComponent control or a control type that is derived from SPMobileComponent is declared on the page. The TemplateName property of the control specifies the ID of a RenderingTemplate. The rendering template is declared in an .ascx file that is located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\CONTROLTEMPLATES. If an object from a SPMobileComponent-derived class is declared on the page, the value of its TemplateName property is determined internally based on the current site definition, the current page type, and the area of the page (Header, Content, or Footer) where the control is declared. If an actual SPMobileComponent object is declared, the TemplateName property is specified in the declaration.

The RenderingTemplate controls that are included with SharePoint Foundation are declared in MobileDefaultTemplates.ascx and GbwMobileDefaultTemplates.ascx. Custom RenderingTemplates are declared in custom .ascx files in the same folder.

The following shows the main markup of the mobile list of lists page, mbllists.aspx. Notice that in some places, such as the Header area of the page for devices that support cascading style sheets (CSS) styles, a SPMobileComponent is declared, and its TemplateName property is explicitly set. But in other places, such as the page Header for devices that do not support CSS, an object of the SPMobileComponent-derived class is declared. In this case, the class is SPMobilePageTitle. On this page, it calls a rendering template with the ID MobileHomePageTitle.

Note

The mobile "HomePage" page type includes pages that are not actually home pages for a site. The type includes pages that do not fit neatly into other categories, such as list view page or form page. For example, the mobile "list of list" page, mbllist.aspx, is of type HomePage.

<SPMobile:SPMobileForm RunAt="Server" PageType="HomePage" Paginate="true">
  <DeviceSpecific>
    <Choice Filter="supportsCss">
      <HeaderTemplate>
        <SPMobile:SPMobileComponent RunAt="Server"Templatename="MobilePageTitleWithCss" Weightless="true" />
      </HeaderTemplate>
      <FooterTemplate>
        <SPMobile:SPMobileComponent RunAt="Server" 
          Templatename="MobilePageNavigationWithCss" Weightless="true" />
      </FooterTemplate>
    </Choice>
    <Choice>
      <HeaderTemplate>
        <SPMobile:SPMobileControlContainer RunAt="Server" Weightless="true">
          <SPMobile:SPMobilePageTitle RunAt="Server" />
          <SPMobile:SPMobileComponent RunAt="Server" 
            TemplateName="MobileDefaultSeparator" />
        </SPMobile:SPMobileControlContainer>
      </HeaderTemplate>
      <FooterTemplate>
        <SPMobile:SPMobileControlContainer RunAt="Server" Weightless="true">
          <SPMobile:SPMobileComponent RunAt="Server" 
            Templatename="MobilePaginateNavigation" />
          <SPMobile:SPMobileComponent RunAt="Server" 
            TemplateName="MobileDefaultSeparator" />
          <SPMobile:SPMobilePageNavigation RunAt="Server" />
        </SPMobile:SPMobileControlContainer>
      </FooterTemplate>
    </Choice>
  </DeviceSpecific>
  <SPMobile:SPMobilePageContents RunAt="Server" />
</SPMobile:SPMobileForm>

Inside the ASCX File

Each RenderingTemplate that is called by the controls on the page has a Template element. The content of the Template element generally matches one of the following patterns.

Direct Calls of ASP.NET Web Controls

In the simplest case, the Microsoft ASP.NET web controls and the SharePoint Foundation web controls that are to be inserted on the mobile page are called directly in the Template element. For example, the MobileDefaultSeparator RenderingTemplate is called from the header and footer areas of several SharePoint Foundation mobile pages. It is defined in MobileDefaultTemplates.ascx with the following markup.

<SharePoint:RenderingTemplate RunAt="Server" id="MobileDefaultSeparator">
  <Template>
    <mobile:Panel RunAt="Server" Alignment="Center" EnableViewState="False">
      <mobile:DeviceSpecific RunAt="Server">
        <Choice Filter="IsMicrosoftMobileExplorer">
          <ContentTemplate>
            <hr width="100%" size="1">
          </ContentTemplate>
        </Choice>
        <Choice Filter="IsHtml32">
          <ContentTemplate>
            <hr width="100%" size="1" color="#D8D8D8">
          </ContentTemplate>
        </Choice>
        <Choice Filter="IsChtml10">
          <ContentTemplate>
            <hr width="100%" size="1">
          </ContentTemplate>
        </Choice>
        <Choice Filter="IsXhtmlMp">
          <ContentTemplate>
            <hr width="100%" size="1" style="color:#D8D8D8" />
          </ContentTemplate>
        </Choice>
        <Choice>
          <ContentTemplate>
            <mobile:LiteralText RunAt="Server" Text="-----" BreakAfter="true" />
          </ContentTemplate>
        </Choice>
      </mobile:DeviceSpecific>
    </mobile:Panel>
  </Template>
</SharePoint:RenderingTemplate>

Notice that the markup declares an ASP.NET Panel control and then styles it according to the markup language that is used by the browser of the mobile device. If the browser does not match any specific type, the default rendering is to create a separator with five hyphens in a LiteralText control.

The following code shows the declaration of the RenderingTemplate. Notice that it calls an SPMobileLabel object.

<SharePoint:RenderingTemplate RunAt="Server" id="MobileFormFieldSeparator">
  <Template>
    <SPMobile:SPMobileLabel RunAt="Server" Text="" BreakAfter="true" />
  </Template>
</SharePoint:RenderingTemplate>

Calls of an SPMobileComponent Object

As noted earlier in the Controls on the Page section, SPMobileComponent controls and controls that derive from SPMobileComponent are used on a SharePoint Foundation mobile page to call rendering templates. So it is not surprising that the Template element of a RenderingTemplate sometimes includes a call to one of these objects. This happens when a portion of the content that the RenderingTemplate needs to render exactly duplicates what is rendered (indirectly) by one of these SPMobileComponent objects. For example, the MobilePageNavigationWithCss RenderingTemplate is defined, in MobileDefaultTemplates.ascx, partly with a call to the SPMobileComponent-derived class SPMobilePageNavigation and partly, also, with a call to a SPMobileComponent object whose TemplateName property is set to MobilePaginateNavigation. The following code shows the declaration.

<SharePoint:RenderingTemplate RunAt="Server" 
  id="MobilePageNavigationWithCss">
  <Template>
    <SPMobile:SPMobileComponent RunAt="Server" 
      Templatename="MobilePaginateNavigation" />
    <SPMobile:SPMobileNoBreakSpace RunAt="Server" />
    <SPMobile:SPMobilePaddedPanel RunAt="Server" BackColor="#F6F6F6">
      <SPMobile:SPMobilePageNavigation RunAt="Server" />
    </SPMobile:SPMobilePaddedPanel>
  </Template>
</SharePoint:RenderingTemplate>

Calls of a Template Selector Object

Sometimes the content of the Template element is an object of a class that derives from SPMobileTemplateSelector. There are nine of these classes:

• SPMobileWebTitle

• SPMobileWebContents

• SPMobileWebNavigation

• SPMobileListContents

• SPMobileListFieldSelector

• SPMobileListNavigation

• SPMobileListTitle

• SPMobilePostsListTitle

• SPMobileWebUrlRedirect

  Note

  SPMobileWebUrlRedirect is used to cause SharePoint Foundation to redirect mobile devices to a custom home page. It is not discussed in this article. For more information, see How to: Customize the Mobile Home Page Through Redirection.

As is suggested by the name of the class from which they derive, these controls select another RenderingTemplate to actually render a part of the page. For example, the MobileHomePageTitle RenderingTemplate mentioned in the Controls on the Page section has SPMobileWebTitle as the value of its Template element. SPMobileWebTitle calls a RenderingTemplate that renders the Header (Title) area of a mobile home page. The following is the declaration of the MobileHomePageTitle rendering template in MobileDefaultTemplates.ascx.

<SharePoint:RenderingTemplate RunAt="Server" id="MobileHomePageTitle">
  <Template>
    <SPMobile:SPMobileWebTitle RunAt="Server" />
  </Template>
</SharePoint:RenderingTemplate>

Each SPMobileTemplateSelector object selects a RenderingTemplate by constructing a segmented ID. The runtime looks, in the .ascx files in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\CONTROLTEMPLATES, for a RenderingTemplate that has a matching ID. For more information about segmented IDs for RenderingTemplates, see Segmented Rendering Template IDs later in this topic. For more information about how the IDs are constructed, see the reference topics for the nine classes listed earlier, and the sections Rendering of Sections on a Mobile Home Page and Rendering of Sections on List View and Form Pages later in this topic.

Mixed Calls

The Template element of a RenderingTemplate can also contain calls to a mixture of the various kinds of controls:

• SPMobileTemplateSelector objects

• SPMobileComponent-derived objects

• SPMobileComponent objects with an explicit TemplateName value

• ASP.NET web controls and the SharePoint Foundation web controls from the Microsoft.SharePoint.MobileControls and Microsoft.SharePoint.WebPartPages namespaces

Any chain of calls that uses SPMobileTemplateSelector objects, SPMobileComponent-derived objects, and SPMobileComponent objects with an explicit TemplateName value must ultimately resolve into calls of controls that the page parser can render in the page description language of the mobile device, such as XHTML.

Segmented Rendering Template IDs

Many of the RenderingTemplates in MobileDefaultTemplates.ascx and GbwMobileDefaultTemplates.ascx have segmented IDs. They can be divided into the following categories:

• Site type variable rendering templates

• List type variable rendering templates

• Field type variable rendering templates

• Simple view list item rendering templates

• Redirection "rendering" templates

• List of blog posts rendering templates

Site Type Variable Rendering Templates

RenderingTemplates whose rendering behavior varies by site definition have segmented IDs in the following format:

IntendedPageUse_SiteTypeID_PageType_PageArea

The possible values for PageArea are Title (the header area of a mobile page), Navigation (the footer area), and Contents.

SiteTypeID is the name or ID number of the site definition of the current website. For the site definitions that are included with SharePoint Foundation, SiteTypeID can be either STS, SGS, or BLOG.

Note

Access from mobile devices is not supported for MPS, CENTRALADMIN, TENANTADMIN, and legacy WIKI sites.

For custom site definitions, SiteTypeID is the ID number (not the name) of the 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.)

Both PageType and IntendedPageUse refer to kinds of mobile pages, but they categorize mobile pages along different axes. PageType refers to the functional purpose of the page from the standpoint of an end user, such as home page, list view page, or edit form. The possible values are the values of the SPMobilePageType enumeration. IntendedPageUse distinguishes a mobile page according to the kind of non-mobile page to which it is intended to correspond; that is, its intended type of target page. The possible values are as follows:

• WebPartMobile – Templates intended for use on summary mobile versions of non-mobile Web Part pages.

• WebPartMobileDetail – Templates intended for use on the detailed mobile version of a non-mobile Web Parts page.

• Moblog – Templates intended for use on a mobile blog site page.

• Mobile – All other mobile pages.

The following are examples:

• Mobile_STS_HomePage_Title

• WebPartMobile_SGS_HomePage_Contents

List Type Variable Rendering Templates

RenderingTemplates whose rendering behavior varies by list definition have segmented IDs have names in the following format:

IntendedListUse_ListTypeID_PageType_PageArea

PageType and PageArea have the same meanings as described in the preceding subsection. ListTypeID is either the ID number of the type of the current list (such as 105) or one of the values of the SPListTemplateType enumeration (such as Contacts). If the list is specified to be part of the site type in the Onet.xml file of the site definition, then ListTypeID is the value the Type attribute of the List element in Onet.xml, which is located in the following directory: %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates\Site_Type\xml. If the list was added to the site in the user interface (UI), then ListTypeID is the ID of the list type that was used as the basis of the new list type.

IntendedListUse identifies what special kind of list, if any, the template is intended to render. The possible values are as follows:

• Mobile – Ordinary list types.

• MobileFolder – Templates intended to render the items in a subfolder of a list.

• MobileDailyView – Templates intended to render the daily list of events from the calendar of a Group Work site.

The following are examples:

• Mobile_Events_NewForm_Navigation

• Mobile_425_EditForm_Contents

Field Type Variable Rendering Templates

Field rendering templates whose rendering behavior varies by the kind of field have segmented IDs with the following format:

MobileCustomListField_ListTypeID_FieldType_Field

ListTypeID has the same meaning as explained in the preceding subsection. FieldType is the data type of the field. It can be any of the values of the SPFieldType enumeration; for example, Text or Number. It can also be a custom field type as defined by the <Field Name="TypeName"> element in the fldtypes*.xml file that defines the custom field type. (For more information about custom field types, see How to: Create a Custom Field Type Definition.) Field is the internal name of the field, such as WorkPhone. If the field is specified to be part of the list in the Schema.xml file for the list definition, the internal name can be found as the value the Name attribute of the Field element in schema.xml, which is located in the following directory: %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES\Feature_Folder. If the field was added to the list in the UI, that is, the Create Column page, then Field is the value of the SPField.InternalName property and can be found only through the object model.

Note

Field is the internal name of the field (column), which is not necessarily the same as the display name of the field. For fields that are created by users in the UI, the internal name is generated by the system from the display name that is chosen by the user. If the user included spaces or punctuation marks in the display name, the internal name will replace these characters with Unicode number of the character bracketed by underscore characters. For example, if a user names a field "Coming Soon", the internal name will be "Coming_x0020_Soon".

The following are examples:

• MobileCustomListField_Posts_DateTime_PublishedDate

• MobileCustomListField_Whereabouts_User_Name

Simple View List Item Rendering Templates

List items can be rendered either for a detailed mobile view or a simple, sometimes called "summary," mobile view. There are some segmented-ID templates to render list items in the simple view. The IDs have the following format:

Mobile_ListTypeID_SimpleViewItemRendering

ListTypeID has the same meaning as in the preceding two subsections.

List of Blog Posts Rendering Templates

SPMobilePostsListTitle chooses either Moblog_MyPosts_Title or Moblog_AllPosts_Title to render the title of a list of posts on a mobile blog site, based on whether the current view type of the blog site is MyPosts or AllPosts.

Redirection "Rendering" Templates

One kind of RenderingTemplate in MobileDefaultTemplates.ascx does not really render anything. Instead, it can be used in the chain of rendering template calls to cause a redirection to a different page. The IDs have the following format:

Mobile_SiteTypeID_PageType_Redirect

SiteTypeID and PageType have the same meaning as in the subsection "Site Type Variable Rendering Templates" earlier in this topic. A rendering template of this type calls SPMobileHomePageRedirection which redirects the request from the mobile device to the page specified in the PageFileName property. The default is mblwp.aspx. The following is the declaration of the rendering template that redirects to the home page of a blog site.

<SharePoint:RenderingTemplate RunAt="Server" 
  id="Mobile_BLOG_HomePage_Redirect">
  <Template>
    <SPMobile:SPMobileHomePageRedirection RunAt="Server" 
      PageFileName="bloghome.aspx" />
  </Template>
</SharePoint:RenderingTemplate>

Rendering of Sections on a Mobile Home Page

As noted, "MobileHomePageTitle" has SPMobileWebTitle as the value of its Template element. SPMobileWebTitle calls a RenderingTemplate that renders the Header (Title) area of a mobile home page. Specifically, it looks for a RenderingTemplate with an ID of Mobile_SiteTypeID_HomePage_Title, where SiteTypeID is the name or ID number of the site definition of the current website.

If a RenderingTemplate for the specific current site definition does not exist in any .ascx file in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\CONTROLTEMPLATES, the rendering system uses Mobile_Default_HomePage_Title (which, in turn, calls a control, SPMobileWeb, that renders the website title with a Label control). For more information about working with the home page RenderingTemplates that are included with SharePoint Foundation, see How to: Customize Mobile Home Pages.

SPMobileWebContents and SPMobileWebNavigation select a RenderingTemplate that renders, respectively, the main page Content area and the Footer (Navigation) area of a mobile home page. So all of the first three selector classes look for RenderingTemplates with IDs on the pattern Mobile_SiteTypeID_HomePage_PageArea.

Rendering of Sections on List View and Form Pages

The SPMobileListTitle, SPMobileListContents, and SPMobileListNavigation classes are used on list view and form pages. They each look for RenderingTemplates with IDs on the pattern Mobile_ListTypeID_PageType_PageArea, where PageType is View, NewForm, EditForm, DispForm, or DeletePage, and ListTypeID is defined in the section Segmented Rendering Template IDs earlier in this topic.

Most of the list types built into SharePoint Foundation are represented by a value in the SPListTemplateType enumeration. The reference topic for that type specifies the underlying integer value of each SPListTemplateType. These integer values were deliberately selected to match the numerical ID of the list type. Therefore, that reference topic is effectively a catalog of the list ID numbers.

There are a few list types that do not have matching values in the enumeration. They are listed in the following table with their ID numbers. You can also use the ID number of custom list types. The ID numbers of custom list types should be numbers above 10000 to ensure that they do not conflict with numbers that will be used by Microsoft in future versions of SharePoint Foundation. Finally, note that Microsoft products that are built on SharePoint Foundation, such as Microsoft SharePoint Server, can and do define additional list types.

ID	Description
151	Help Library
400	Schedule
401	FC Groups
425	What’s New
1210	Distribution Lists

If a RenderingTemplate with an ID that specifies the current list type does not exist, a RenderingTemplate with an ID on the pattern Mobile_Default_PageType_PageArea is used. For more information about working with the list rendering RenderingTemplates that ship with SharePoint Foundation, see How to: Customize Mobile List View and Form Pages.

Field Rendering

SPMobileListFieldSelector selects RenderingTemplates that render particular fields on list view, New, Edit, or Display pages. It looks for a RenderingTemplate with an ID that uses the following pattern: MobileCustomListField_ListTypeID_FieldType_Field, as defined earlier in this topic in the section Segmented Rendering Template IDs.

If there is no RenderingTemplate with the ID that is being sought, then the RenderingTemplate with the ID MobileDefaultListField is used. For more information about working with the field rendering RenderingTemplates that ship with SharePoint Foundation, see How to: Customize Field Rendering on Mobile Pages.

How Field Rendering for Mobile Devices Differs from Field Rendering for Computers

In SharePoint Foundation, field rendering with custom field rendering controls for mobile devices is similar to field rendering with custom field rendering controls for computers. But consider these differences:

• Mobile pages are an entirely different type of pages from the non-mobile pages and they reference a different set of RenderingTemplates.

• Mobile RenderingTemplates are declared in MobileDefaultTemplates.ascx and GbwMobileDefaultTemplates.ascx, not in DefaultTemplates.ascx.

• Mobile field rendering controls have their own namespace, Microsoft.SharePoint.MobileControls (rather than Microsoft.SharePoint.WebControls), and they derive from classes in the ASP.NET System.Web.UI.MobileControls namespace, rather than System.Web.UI.WebControls.

• The inheritance hierarchy for mobile field rendering controls is different from that of regular field rendering controls. For example, the functions of the TemplateBasedControl and FormComponent in regular field rendering are combined in the SPMobileComponent class.

• Custom field rendering controls you create for mobile contexts rely more on the CreateChildControls method of the control to render a field, and correspondingly less on the rendering template, than is the case for custom field rendering controls that you create for computer browsers. Moreover, in mobile field rendering, controls do not often override the CreateChildControls method itself. Instead, you typically override one or more of four other methods that are called by CreateChildControls: CreateControlForDisplay, CreateControlForEdit, CreateControlForNew, and CreateControlForView. For more information about custom field rendering, see How to: Create a Custom Field Type and Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages.

Nesting RenderingTemplates

RenderingTemplates can be nested. See the example in How to: Customize Mobile Home Pages.

See Also

Tasks

Walkthrough: Customizing a Mobile Home Page

How to: Customize Mobile List View and Form Pages

Walkthrough: Customizing a Mobile List View Page

How to: Customize Mobile Home Pages

Walkthrough: Customizing Item Titles on Mobile Forms

How to: Customize Field Rendering on Mobile Pages

Concepts

Overview of Mobile Pages and the Redirection System

Layout and Pagination of Mobile Pages

Ellipses and Rendering Limits

How to: Create a Custom Field Type Definition

Understanding Schema.xml Files

Understanding Onet.xml Files