Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages

Article
05/05/2014

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This walkthrough shows how to customize field rendering on mobile pages by implementing a custom field rendering control in conjunction with a RenderingTemplate. 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 navigate to the MSN News search result page.
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

Completion of Walkthrough: Customizing Item Titles on a Mobile Display Form.

Prepare for Development of Custom Field Rendering Controls

In Visual Studio, select External Tools from the Tools menu.
In the External Tools dialog, click Add and enter Get Assembly Public Key for the Title.
Fill the Command textbox by browsing to sn.exe. It is usually at C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin\sn.exe.
In the Arguments textbox, type the following (case sensitive) -Tp "$(TargetPath)".
Enable the Use Output window checkbox.
Click OK. The new command is added to the Tools menu.

To set up the custom field project:

In Visual Studio, select New Project on the File menu.
In the New Project dialog box, select Visual C# in the Project types box, select Class Library in the Templates box, and enter ItemTitleField in the Name box. Click OK.
Right-click the References node in Solution Explorer, click Add Reference, and, while holding down the CTRL key, select System.Web, System.Web.Mobile, and Microsoft SharePoint Services on the .NET tab in the Add Reference dialog box. Click OK.
Right-click the project name in Solution Explorer and select Properties.
On the Application tab of the Properties dialog, enter MyCompany.SharePoint.MobileControls.ItemTitleField as the Assembly name and MyCompany.SharePoint.MobileControls as the Default namespace. Replace MyCompany with your company's name. Throughout this walkthrough, replace MyCompany with your company's name.
Open the Signing tab and then select Sign the assembly.
Choose <New...> from the Choose a strong name key file drop-down list box.
In the Create Strong Name Key dialog, type ItemTitleField.snk in the Key file name box, and then be sure that the Protect ... check box is not checked. Click OK. Open the Build Events tab and type the following (below) in the Post-build event command line box. This code ensures that each time you rebuild the project, the latest versions of your project files are copied to the correct location and that Windows SharePoint Services 3.0 is restarted so it will load the latest version of the assembly.
```
cd "$(ProjectDir)"
"%programfiles%\microsoft visual studio 8\sdk\v2.0\bin\gacutil" /i "$(TargetPath)" /nologo /f
%systemroot%\system32\iisapp.vbs /a "SharePoint_App_Pool" /r
xcopy *.ascx "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\CONTROLTEMPLATES\" /y
```
Replace SharePoint_App_Pool with the actual name of the Internet Information Server (IIS) Application Pool that is assigned to your Windows SharePoint Services Web Application. This is usually the same name as the IIS Web Site that holds the application; for example, "SharePoint - 80". (The quotation marks can be omitted if there are no spaces in the name.)
Click in any other enabled control on the tab so that Visual Studio detects your changes and an asterisk appears on the tab label.
Click the Save all files button on the toolbar.
In Solution Explorer, rename the file Class1.cs to ItemTitleField.cs.

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;
```
Change the namespace to MyCompany.SharePoint.MobileControls.
Replace the entire Class1 declaration with the following code:
```
public class ItemTitleField : SPMobileBaseTextField
{

}// end ItemTitleField class
```
Notice that your new class inherits from SPMobileBaseTextField.

Add the following override of the [M:Microsoft.SharePoint.MobileControls.SPMobileBaseFieldControl.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 = "http://search.msn.com/results.aspx?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 ItemFieldValue.

Add the following override of the [M:Microsoft.SharePoint.MobileControls.SPMobileBaseTextField.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 [M:Microsoft.SharePoint.MobileControls.SPMobileBaseTextField.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;
}

Select Build on the Build menu. You are not finished yet, but you need to compile the assembly at this point so that you can generate a Public Key Token.

To create the rendering template

In Solution Explorer, right-click the project name, ItemTitleField, and select Add, then New Item.
Select Visual C# Project Items in the Categories window and then Text File in the Templates window.
In the Name box, type AnnouncementsItemTitleField.ascx and click Add. (Do not put the file in a subfolder of the project folder or the Post-build commands that you created will not find it.)

In the AnnouncementsItemTitleField.ascx file that is created add the following markup:

<%@ Control Language="C#" %>
<%@ Assembly Name="Microsoft.SharePoint, Version=12.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=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> 
<%@ Register TagPrefix="SPMobile" Namespace="Microsoft.SharePoint.MobileControls" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register TagPrefix="CustomMobile" Namespace="MyCompany.SharePoint.MobileControls" Assembly="MyCompany.SharePoint.MobileControls.ItemTitleField, Version=1.0.0.0, Culture=neutral, PublicKeyToken=Token" %> 
<%@ Import Namespace="Microsoft.SharePoint" %>

<SharePoint:RenderingTemplate RunAt="Server" ID="MobileCustomListField_Announcements_Text_Title" >
    <Template>
      <CustomMobile:ItemTitleField RunAt="Server" /> 
    </Template>
</SharePoint:RenderingTemplate>

Replace MyCompany with your company name in both places.
Replace Token with the actual Public Key Token which you obtain by clicking Get Assembly Public Key on the Tools menu. The key token will appear in the last line of the Output window. Use only the key token, not the entire key.

Notice that this file is nearly identical to the one created in Walkthrough: Customizing Item Titles on a Mobile Display Form. The differences are:
- The line
  
  <mobile:Label Text="Title field in Announcements List" RunAt="Server" />
  
  in Walkthrough: Customizing Item Titles on a Mobile Display Form
  
  is replaced in this topic example code with the line
  
  <CustomMobile:ItemTitleField RunAt="Server" />
  
  so that the rendering template will call the field rendering control that you created earlier in this walkthrough.
- A new Register directive has been added to register the "CustomMobile" tag prefix.
Save and close the file.
Select Rebuild from the Build menu.

Testing the Rendering Control

With your mobile device or emulator, navigate to a Web site in your Web application that has an Announcements list. Navigate to the Announcements list. Click the New Item link. You should see something like this:

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

Create a new item and give it an Expires value that is some past date. Click Save. This will take you back to the list view. Click the Display link under the new item. You should see something like this. Note the Search link that has been added to the end of the title.

Figure 2. Search link added to Display form

Click the Edit link. You should see something like this. Note the "OVERDUE" that has been added to the current title.

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

Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages

Prerequisites

Prepare for Development of Custom Field Rendering Controls

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