How to: Customize Field Rendering on Mobile Pages

  • Article

Applies to: SharePoint Foundation 2010

This topic provides an overview of the basic procedure for customizing field rendering on Microsoft SharePoint Foundation pages that can be accessed by mobile devices. For detailed walkthroughs of the procedure, see Walkthrough: Customizing Item Titles on Mobile Forms and Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages.

The rendering of a field on a list view page or form always begins with an SPMobilePageContents object in the Body (Contents) area of the page. As described in Mobile Page Rendering System, this object starts 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 rendering of a field by creating a RenderingTemplate with the ID for which the runtime will be looking.

Specifically, the runtime looks for a RenderingTemplate with an ID of the form MobileCustomListField_ListTypeID_FieldType_Field.

The placeholders, ListTypeID, FieldType, and Field, are defined in Segmented Rendering Template IDs.

If no RenderingTemplate with an ID that is being sought exists, the RenderingTemplate with the ID MobileDefaultListField is used.

Existing RenderingTemplates

The following list identifies RenderingTemplates for field rendering that already exist in MobileDefaultTemplates.ascx or GwbMobileDefaultTemplates.ascx when SharePoint Foundation is installed.

  • MobileCustomListField_Contacts_Text_WorkZip

  • MobileCustomListField_PictureLibrary_Computed_ImageSize

  • MobileCustomListField_Posts_DateTime_PublishedDate

  • MobileCustomListField_Events_UserMulti_ParticipantsPicker

  • MobileCustomListField_CallTrack_DateTime_CallTime

  • MobileCustomListField_CallTrack_Computed_RefDetail

  • MobileCustomListField_Whereabouts_User_Name

You cannot modify the MobileDefaultTemplates.ascx or GwbMobileDefaultTemplates.ascx files. You can create new RenderingTemplate elements with the same names (in your own .ascx file), but there is a risk that you will break other solutions that are installed at the SharePoint Foundation deployment that depend on the original RenderingTemplate elements with these names.

Note

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

In addition, there is already a default RenderingTemplate element with the ID MobileDefaultListField. This is used by the runtime whenever a RenderingTemplate for the current list and field is not defined. The same risk is present if you create a new RenderingTemplate with this name.

To customize a section of a mobile list view or form 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 Controlin 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: MobileCustomListField_ListTypeID_FieldType_Field.

    • ListTypeID is either the ID number of a type of the current list (such as 105) or one of the values of the SPListTemplateType enumeration (such as Contacts).

    • FieldType is the data type of the field, and Field is the name of the internal name of the field. For more information about what can replace these placeholders, see Mobile Page Rendering System.

    Your rendering template can directly declare renderable controls, such as Label controls, or it can declare a rendering control of a class that is derived from SPMobileBaseFieldControl.

  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 to create a new Title field for items on Announcements lists. For detailed examples, see Walkthrough: Customizing Item Titles on Mobile Forms and Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages.

<SharePoint:RenderingTemplate RunAt="Server" ID="MobileCustomListField_Announcements_Text_Title" >
  <Template>
    <mobile:Label Text="Title field in Announcements List" RunAt="Server" />
  </Template>
</SharePoint:RenderingTemplate>

See Also

Tasks

Walkthrough: Customizing Item Titles on Mobile Forms

Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages

Concepts

How to: Create a Custom Field Type Definition

Understanding Schema.xml Files

Understanding Onet.xml Files