How to: Customize Field Rendering on Mobile Pages

  • Article

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 topic provides an overview of the basic procedure for customizing field rendering on Windows SharePoint Services 3.0 pages accessible to mobile devices. For detailed walkthroughs of the procedure, see Walkthrough: Customizing Item Titles on a Mobile Display Form and Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages.

As described in Mobile Page Rendering System, an SPMobileListFieldSelector template selector control is called, through a chain of calls, from a control on the page.

This object determines, based on the current list type and field (which are Announcements and Title, respectively, in this example), which RenderingTemplate renders the field on the mobile Display page.

The control looks for a RenderingTemplate named MobileCustomListField_ListTypeID_FieldType_Field.

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 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, then the internal name can be found as the value the Name attribute of the Field element schema.xml, which is located in the following directory: Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\12\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 created by users in the UI, the internal name is generated by the system from the display name chosen by the user (in the Column name box of the Create Column page). If the user included spaces or punctuation marks in the display name, the mobile template rendering system will not be able to work with the internal name that is generated, so you will not be able to customize the rendering of such fields.

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: Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SITETEMPLATES\Site_Type\xml. (For a list of the ID numbers of all list types that ship with Windows SharePoint Services 3.0, see Mobile Page Rendering System.) If the list was added to the site in the UI; that is, the New (list) page, then ListTypeID is the ID of the list type that was used as the basis of the new list type. This is determined by what link the user clicked on the Create page (create.aspx) in order to get to the New page.

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

Existing RenderingTemplates

The following list identifies RenderingTemplates for field rendering that already exist in MobileDefaultTemplates.ascx when Windows SharePoint Services is installed.

  • MobileCustomListField_Contacts_Text_WorkPhone

  • MobileCustomListField_Contacts_Text_HomePhone

  • MobileCustomListField_Contacts_Text_CellPhone

  • MobileCustomListField_Contacts_Text_Email

  • MobileCustomListField_PictureLibrary_Computed_ImageSize

  • MobileCustomListField_Posts_DateTime_PublishedDate

You may not modify the MobileDefaultTemplates.ascx file. You can create new RenderingTemplate elements with the same names (in your own .aspx file), but there is a risk that you will break other solutions installed at the Windows SharePoint Services deployment that depend on the original RenderingTemplate elements with these names.

Note

The RenderingTemplates that ship with Windows SharePoint Services 3.0 load before custom rendering templates load, so when a custom rending template with 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 will override 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, Notepad, or a text editing application, create a user control file (.ascx) in the the path \Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\CONTROLTEMPLATES.

  2. To register or import the appropriate namespaces, add the necessary page directives to the .ascx file.

  3. Add a rendering template to the .ascx file and give it an ID in the following format: MobileCustomListField_ListTypeID_FieldType_Field.

    • ListTypeID 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). See above for details.

    • FieldType is the data type of the field. See above for details.

    • Field is the name of the field. See above for details.

    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.

  4. Save the .ascx file and reset Internet Information Services (IIS) to effect your changes.

Example

The following example of a RenderingTemplate definition shows how to create a new Title field for items on Announcement lists. For detailed examples, see Walkthrough: Customizing Item Titles on a Mobile Display Form 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 a Mobile Display Form

Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages

Concepts

Custom Field Type Definition

Schema.xml

Onet.xml