Extending the SharePoint:FieldValue WebControl

How many times did you try to incorporate some extra rules or formatting into Page Layouts? Formatting a date is just one of the many examples solving which can cause you spent many hours trying to using the out-of-the-box available controls. The SharePoint:FieldValue is probably the most commonly used control, especially in Page Layouts where you don't want to use the Edit-in-place experience. Yet this control doesn't have any customization or formatting possibilities. That's why some time ago me and my colleagues at Imtech ICT Business Solutions have thought about creating our version of this control with some more formatting properties. As soon as we have created it, we have started benefiting from it: because we had the code of it, extending it with extra functionality is just a piece of cake. Anyway, let me introduce you the Imtech:PageProperty control.

I would like to guide you through a process of creating a simple yet powerful custom WebControl. At the end of this post you should be able to use the example we will build here and extend it with new functionality to make it fit to your needs.

I assume you know the basics of working with WebControls within SharePoint 2007. Furthermore I assume already have a project, which builds into an assembly. I also assume that it's content is available within SharePoint. If you are a beginner in SharePoint and have questions about these steps, please react in the comment so others will be able to learn from it too.

We start by creating a new public class deriving from the System.Web.UI.WebControls.WebControl class to provide the basic functionality of a WebControl:

using System;  
using System.Collections.Generic;  
using System.Text;  
using System.Web.UI.WebControls;  
using System.Web.UI;

namespace WebControls  
{
    [ToolboxData("<{0}:PageProperty runat=\"server\" />")]
    public class PageProperty : WebControl
    {
    }
}

Then you need to define the attributes to use within the control. If you look at the SharePoint:FieldValue control, you see you can pass the name of the field of which the value you want to display. This guarantees the flexibility and reusability of the control. Let us do the same:

private string _Property;

[Bindable(true), DefaultValue(""), Localizable(false)]
public string Property  
{
    get { return _Property; }
    set { _Property = value; }
}

Because we have called our control PageProperty I have chosen for the name Property instead of FieldName, but you are free to choose the one which suits you most.

Let's test the control now. At this stage the control should be able to display the value of the Field passed through the Property attribute. To display this value we need to override the Render method of the control. Another option would be overriding the RenderContents method but it would cause your control to render a span or any other element around the contents which isn't desired in WCM scenario's when you deal with predefined layouts.

protected override void Render(HtmlTextWriter writer)  
{
  try
  {
    writer.Write(
       SPContext.Current.Item[Property].ToString()
    );
  }
  catch { }
}

Let's move on with adding the formatting logic. In our control we have decided to split this routine in two pieces: defining the type of the value and passing the desired date format. Without the first part you might end up trying to format a text string as a date. Let us define the two properties we require. Second of all choosing for this approach will allow you to use various formatting routines for various data types.

public enum PropertyType  
{
    String,
    Number,
    Date
}

private PropertyType _Type;  
[Bindable(true), DefaultValue(""), Localizable(false)]
public PropertyType Type  
{
    get { return _Type; }
    set { _Type = value; }
}

private string _Format;

[Bindable(true), DefaultValue(""), Localizable(false)]
public string Format  
{
    get { return _Format; }
    set { _Format = value; }
}

I have chosen for an enumeration to pass the data type to ensure the input within this attribute more easily. Using a string would work as well. Still it's not a best practice typing the possible values over and over again.

As we have the required attributes we can move on to actually implementing the formatting routine. We will do it by extending the Render method we have defined at the beginning.

try  
{
  string fieldValue =
      SPContext.Current.Item[_Property].ToString();

  switch (_Type)
  {
    case PropertyType.Date:
      fieldValue =
         DateTime.Parse(fieldValue).ToString(Format);
      break;
  }

  writer.Write(fieldValue);
}
catch { }  

The switch block contains only one case at this moment. You could easily extend it though for example with extra logic for formatting numbers.

The control is ready. You can use it within your Page Layouts as follow:

<Imtech:PageProperty Property="Modified"  
Format="d MMMM" Type="Date" runat="server"/>  

The last piece is to register your newly created control within all Page Layouts or simply once in web.config - approach I prefer.

The PageProperty WebControl allows you to replace the SharePoint:FieldValue control. Extending it with new features will allow you to box the functionality and avoid unnecessary complicated constructions in your Page Layouts or queries. The downside is you need to be a developer to do this and you must be allowed to deploy custom code on the web server.

Comments

comments powered by Disqus