Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages

Article
10/20/2016

Applies to: SharePoint Foundation 2010

This walkthrough shows how to customize field rendering on mobile pages by implementing a custom field rendering control together with a RenderingTemplate object. The example procedure shows how to customize the Title field of an item in an Announcements list on the mobile Display item, New item, and Edit item pages. The customization is different for the three kinds of pages:

Display form — Adds a search link through which users can use Bing to search the Internet for the announcement title.
Edit form — Adds default text when the value of the Expires column is less than the current date.
New form — Adds default text to show users a specific format for values.

For an overview of the steps in customizing fields on mobile pages, see How to: Customize Field Rendering on Mobile Pages.

Prerequisites

Do at least one of these:

Create a tool to get the full name of an assembly and add it to the Tools menu in Microsoft Visual Studio. For more information, see How to: Create a Tool to Get the Full Name of an Assembly.
Create a tool to get the public key of an assembly and add it to the Tools menu in Visual Studio. For more information, see How to: Create a Tool to Get the Public Key of an Assembly.

Recommended: Complete the walkthrough described in Walkthrough: Customizing Item Titles on Mobile Forms.

To set up the custom field project

In Visual Studio, create an Empty SharePoint Project. Make it a farm solution, not a sandboxed solution; and name it MobileItemTitleField.
In Solution Explorer, right-click the project name, and select Properties.
On the Application tab of the Properties dialog box, enter Contoso.SharePoint.MobileControls.ItemTitleField as the Assembly name, and enter Contoso.SharePoint.MobileControls as the Default namespace. Leave the Target framework set to .NET Framework 3.5.
If the Solution Platforms box on the Visual Studio Standard Menu does not say "Any CPU" or "x64", open the Build tab and set the Platform Target to either "Any CPU" or "x64". For information about making the choice, see How to: Set the Correct Target Framework and CPU.
Click the Save all files button on the toolbar.
Right-click the project name in Solution Explorer, point to Add, and then select New Item.
In the Add New Item dialog box, select Visual C#, and then select Code in the Installed Templates tree.
In the Templates box, select Class, and in the Name box, type ItemTitleField.cs. Click Add.
In Solution Explorer, right-click the References node, and then click Add Reference. While holding down the CTRL key, select System.Web and System.Web.Mobile on the .NET tab in the Add Reference dialog box. Click OK.
In Solution Explorer, right-click the project name, point to Add, and then select SharePoint Mapped Folder.
Use the tree control that opens to map the folder to TEMPLATE\ControlTemplates, and then click OK.
In Solution Explorer, right-click the new ControlTemplates folder (not the project name), point to Add, and then select New Item.
In the Add New Item dialog box, in the Installed Templates tree, select SharePoint, and then select 2010.
In the Templates box, select a SharePoint User Control, and give the .ascx file the name AnnouncementsItemTitleField.ascx. Click Add. 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. It also adds the assembly to the manifest and sets it to be deployed to the global assembly cache.

Tip

Do not add the User Control by right-clicking the project name 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.
Delete the AnnouncementsItemTitleField.ascx.cs and AnnouncementsItemTitleField.ascx.designer.cs files that are created automatically under the AnnouncementsItemTitleField.ascx file. They are not needed for this project. The default content of AnnouncementsItemTitleField.ascx refers to the AnnouncementsItemTitleField.ascx.cs file that you just deleted, and the compiler gives you a warning about the missing file. Ignore the warning: the default content is changed in a step later in this topic.

To create the rendering control

Open the ItemTitleField.cs file of the project, if it is not already open, and add the following using statements.
```
using System.Web.UI.MobileControls;
using Microsoft.SharePoint;
using Microsoft.SharePoint.MobileControls;
```
Add the public access modifier to the ItemTitleField declaration, if it is not already there, and modify the declaration to specify that it inherits from SPMobileBaseTextField.
```
public class ItemTitleField : SPMobileBaseTextField
{

}
```

Add the following override of the CreateControlForDisplay() method.

protected override MobileControl CreateControlForDisplay()
{
   string title = Convert.ToString(this.ItemFieldValue);
   if (!String.IsNullOrEmpty(title))
   {
      this.LabelControl.BreakAfter = false;
      this.LabelControl.Text = title + " ";

      this.LinkControl.BreakAfter = false;
      this.LinkControl.Text = "Search";
      this.LinkControl.href = "https://www.bing.com/search?q=" + title.Replace(' ', '+');

      Panel panel = new Panel();
      panel.BreakAfter = false;
      panel.Controls.Add(this.LabelControl);
      panel.Controls.Add(this.LinkControl);

      return panel;
   }
   return null;
}

Notice that this method begins by getting the current value of the Title field of the current list item. This current value is stored in the ItemFieldValue property.

Add the following override of the CreateControlForNew method.

protected override MobileControl CreateControlForNew()
{
   MobileControl myNewControl = null;
   if (this.Field != null)
   {
      string text = "Group: Project Name";
      if (!this.Page.IsPostBack)
      {
         this.TextBoxControl.Text = text;
      }
      myNewControl = this.TextBoxControl;
   }
   return myNewControl;
}

Add the following override of the CreateControlForEdit method.

protected override MobileControl CreateControlForEdit()
{
   MobileControl myEditControl = null;
   if (this.Item != null && this.Field != null)
   {
      if (this.NeedEllipsisRendering)
      {
         myEditControl = this.CreateControlForDisplay();
      }
      else
      {
         if (!this.Page.IsPostBack)
         {
            string strEdit = this.Field.GetFieldValueForEdit(this.ItemFieldValue);
            string overDue = "OVERDUE: ";

            SPListItem item = this.ListItem;
            if (item["Expires"] != null)
            {
               System.DateTime date = (DateTime)item["Expires"];
               if (date.CompareTo(System.DateTime.Today) < 0)
               {
                  this.TextBoxControl.Text = overDue + strEdit;
               }
               else
               {
                  this.TextBoxControl.Text = strEdit;
               }
            }
         }
         myEditControl = this.TextBoxControl;
      }
   }
   return myEditControl;
}

To create the rendering template

Open the AnnouncementsItemTitleField.ascx file, and replace the entire directives section 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" %>

Add an additional tag prefix registration with the following code.
```
<%@ Register TagPrefix="Contoso" Namespace="Contoso.SharePoint.MobileControls" Assembly="$SharePoint.Project.AssemblyFullName$" %> 
```
The Visual Studio token $SharePoint.Project.AssemblyFullName$ is replaced with the four-part assembly name when the project is built.
Add an Import directive for the Microsoft.SharePoint namespace.
```
<%@ Import Namespace="Microsoft.SharePoint" %>
```
Below the directives, add a RenderingTemplate, and give it the ID that the runtime is looking for: MobileCustomListField_Announcements_Text_Title.
```
<SharePoint:RenderingTemplate RunAt="Server" ID="MobileCustomListField_Announcements_Text_Title" >

</SharePoint:RenderingTemplate>
```
Inside the RenderingTemplate element, define a Template element that has your custom ItemTitleField object as a child control.
```
<Template>
  <Contoso:ItemTitleField RunAt="Server" />
</Template>
```
Notice that this file is similar to the one that is created in Walkthrough: Customizing Item Titles on Mobile Forms. The differences are as follows:
- A new Register directive is added to register the "Contoso" tag prefix.
- A line that imports the Microsoft.SharePoint namespace is added.
- The following line is in Walkthrough: Customizing Item Titles on Mobile Forms:
  
  <mobile:Label Text="Title field in Announcements List" RunAt="Server" />
  
  This line is replaced in this topic example code with this line:
  
  <Contoso:ItemTitleField RunAt="Server" />
  
  This enables the rendering template to call the field rendering control that you created earlier in this walkthrough.
On the Build menu, select Deploy Solution. This automatically rebuilds the assembly, saves the .ascx file, deploys the assembly to the global assembly cache, deploys the .ascx file to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATES\ControlTemplates, and recycles the web application.

Testing the Rendering Control

With your mobile device or emulator, navigate to a website in your web application that has an Announcements list. Navigate to the Announcements list. Click the New Item link. You should see something like Figure 1.

Figure 1. Default text specified for Title field in New form

Customized Mobile New Item Form

Create a new item and give it an Expires value that is some past date. Click Save. This takes you back to the list view. Click to display the new item. You should see something like Figure 2. Notice that the Search link was added to the end of the title.

Figure 2. Search link added to Display form

Customized Mobile Display Item Form

Click the Edit link. You should see something like Figure 3. Notice that "OVERDUE" was added to the current title.

Figure 3. Conditional rendering of text in Title field of Edit form

Customized Mobile Edit Item Form

Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages

Prerequisites

To set up the custom field project

To create the rendering control

To create the rendering template

Testing the Rendering Control

See Also

Tasks

Concepts

Additional resources