Building Custom Field Types in Windows SharePoint Services 3.0

Applies to:  2007 Microsoft Office System, Windows SharePoint Services 3.0, Microsoft Visual Studio 2005 Extensions for Windows SharePoint Services 3.0

Joel Krist, iSoftStone

July 2007

When storing business information in Windows SharePoint Services 3.0, you might experience scenarios in which important business data does not conform to the field types included in Windows SharePoint Services, or situations in which you need to further customize those general field types. Windows SharePoint Services offers the ability to create custom field types, based on the robust set of base field types it provides. These custom fields can include custom data validation, custom field rendering, and custom field property rendering and processing. Microsoft Visual Studio 2005 Extensions for Windows SharePoint Services 3.0 gives new support for creating custom SharePoint field types. This Office Visual How To shows what you need to do to build a custom field type for Windows SharePoint Services 3.0 by using Microsoft Visual Studio 2005 with Extensions for Windows SharePoint Services 3.0. The field type created here provides you with the ability to select a logo image from a list box.

Watch the Video Length: 09:35 | Size: 7.89 MB | Type: WMV

Code It | Read It | Explore It

Code It

To show how to build a custom field type, this section walks through four key steps:

1. Creating an empty Windows SharePoint Services application project in Microsoft Visual Studio.

2. Adding a SharePoint field control to the project.

3. Adding functionality to the field control.

4. Building and deploying the custom field type to a SharePoint site.

Creating an Empty SharePoint Application Project in Visual Studio 2005

Before you can customize your new field type, you must create a SharePoint application project.

To create an empty SharePoint application project in Visual Studio 2005

1. Start Visual Studio.

2. On the File menu, click New, and then click Project.

3. In the Project Types pane of the New Project dialog box, select Visual C#, and then select the SharePoint category.

4. In the Templates pane, click Empty. Specify a Name and Location for the project, and then click OK. Visual Studio creates a solution that contains an empty project.

Adding a Field Control to the Project

Visual Studio Extensions for Windows SharePoint Services 3.0 provides support for creating SharePoint field types through the Field Control project item.

To add a field control to the empty project

1. In the Visual Studio Solution Explorer, right-click the empty project created in the previous procedure, click Add, and then click New Item.

2. In the Categories pane of the Add New Item dialog box, expand the Visual C# Project Items node, and then select the SharePoint category.

3. In the Templates pane, click Field Control. Specify LogoField for the Name of the field control, and then click Add. Visual Studio adds the new field control to the project.

Adding Functionality to the Field Control

Visual Studio adds two Microsoft Visual C# code files to the project: LogoField.FieldControl.cs and LogoField.Field.cs. The LogoField.Field.cs file contains code that defines a class that by default is derived from the SPFieldText class and that overrides the FieldRenderingControl property. The generated implementation of this property returns an instance of the Visual Studio–generated LogoFieldFieldControl field control class that is defined in LogoField.FieldControl.cs. The LogoFieldFieldControl class implements the rendering, validation, and processing support provided by the field control.

To add functionality to the LogoFieldFieldControl class to provide users with the ability to select a logo image from a list box

1. In the Visual Studio Solution Explorer, open the LogoField.FieldControl.cs file.

2. Add the following using statements to the top of the file, after the Visual Studio–generated using statements.

   Using System.Web.UI;
   Using System.Web.UI.WebControls;
   Using System.Web.UI.HtmlControls;
   

3. Add the following code inside the definition of the LogFieldFieldControl class.

   private ListBox listBox;
   private HtmlTable table;
   
   protected override void CreateChildControls()
   {
       base.CreateChildControls();
   
       this.table = new HtmlTable();
   
       HtmlTableRow row = new HtmlTableRow();
       table.Rows.Add(row);
   
       HtmlTableCell cell = null;
   
       if (this.ControlMode == SPControlMode.Edit || 
           this.ControlMode == SPControlMode.New)
       {
           cell = new HtmlTableCell();
           cell.ColSpan = 2;
           cell.Attributes["class"] = "ms-formdescription";
           cell.InnerText = "Choose a logo:";
   
           row.Cells.Add(cell);
   
           row = new HtmlTableRow();
           cell = new HtmlTableCell();
   
           // Create a logo selector listbox.
           this.listBox = new ListBox();
           this.listBox.Rows = 12;
   
           // Get the list of logo images from the Logos picture library
           // and add them to the listbox.
           SPSite site = SPContext.GetContext(this.Context).Site;
   
           SPDataSource dataSource = new SPDataSource();
           dataSource.List = site.RootWeb.Lists["Logos"];
   
           this.listBox.DataSource = dataSource;
           this.listBox.DataTextField = "Title";
           this.listBox.DataValueField = "Name";
   
           this.listBox.DataBind();
   
           // Get the current value of the field.
           string currentValue = (string)this.ItemFieldValue;
   
           if (currentValue != null && currentValue != string.Empty)
           {
               this.listBox.SelectedValue = currentValue;
           }
           else if (this.listBox.Items.Count > 0)
           {
               this.listBox.SelectedIndex = 0;
           }
   
           // Add the script that updates the preview image when a new
           // item is selected in the lisbox.
           this.listBox.Attributes["onchange"] = 
               "document.all.imgLogoPreview.src = '/logos/' + " +
               "this.options[this.selectedIndex].value;";
   
           cell.Controls.Add(this.listBox);
           row.Cells.Add(cell);
           table.Rows.Add(row);
       }
   
       cell = new HtmlTableCell();
   
       LiteralControl literalControl = new LiteralControl();
   
       string logo = null;
       object logoObject = this.ItemFieldValue;
   
       if (logoObject != null)
       {
           logo = (string)logoObject;
       }
   
       if (logo == null || logo == string.Empty)
       {
           logo = this.listBox.SelectedValue;
       }
   
       literalControl.Text = 
           "<img id='imgLogoPreview' src='/logos/" + logo + "'></img>";
   
       cell.Controls.Add(literalControl);
       row.Cells.Add(cell);
   
       base.Controls.Add(table);
   }
   
   public override void UpdateFieldValueInItem()
   {
       this.EnsureChildControls();
   
       try
       {
           this.Value = this.listBox.SelectedValue;
           this.ItemFieldValue = this.Value;
       }
       catch
       {
           ;
       }
   }
   
   protected override void Render(HtmlTextWriter output)
   {
       this.table.RenderControl(output);
   }
   

4. Save the changes to the LogoField.FieldControl.cs file.

The preceding code assumes that the top-level Web site of the site collection contains a picture library named Logos that contains image files. For the field control to retrieve and display the list of logos, this library must exist and contain image files. For more information about creating picture libraries in Windows SharePoint Services, see Working with SharePoint picture libraries on Microsoft Office Online.

Building and Deploying the Custom Content Type

The field control project is now ready to build and deploy. On the Visual Studio Build menu, click Deploy Solution. Visual Studio builds the assembly for the field control and generates the necessary configuration files for the solution's deployment. It then deploys the solution to the SharePoint site.

You can now test the new field type in Windows SharePoint Services by associating the field type with a list. For more information about associating a field type with a list, see Add a column to a list on Microsoft Office Online.

Read It

This Office Visual How To shows how to build a custom field type in Windows SharePoint Services 3.0 by using Microsoft Visual Studio 2005 with Extensions for Windows SharePoint Services 3.0. The key steps include:

1. Creating an empty SharePoint application project in Visual Studio.

2. Adding a SharePoint field control to the project.

3. Adding functionality to the field control.

4. Building and deploying the custom field type to a SharePoint site.

Explore It

For additional information, see the following resources:

• Custom Field Types

• How to: Create a Custom Field Type and Field Control

• SPFieldText Class (Microsoft.SharePoint)

• Adding Columns in Content Types to Lists

• Windows SharePoint Services Developer Center

• Office Developer Center