Custom Properties in SharePoint 2010 Visual Web Parts

SharePoint 2010 Visual Web Parts contain a set of properties that we can use to control its appearance and behavior during runtime. Sometimes we might need to add our own properties to a Web Part so that we can implement more generalized controls, which can be plugged-in to different pages based on a mode or a category.

If I just add a Visual Web Part with the default name “VisualWebPart1” to my SharePoint project, I will get a User Control (called “VisualWebPart1UserControl.ascx”) and a Web Part class (called “VisualWebPart1.cs”) inheriting from the WebPart base class. This VisualWebPart1.cs is used to load the User Control as well as to set personalization settings. So I have to add my custom property to the VisualWebPart1.cs.

So the basic steps to add a custom property are;

1. Add a custom property in “VisualWebPart1.cs” Web Part class
2. Make above custom property visible to “VisualWebPart1UserControl.ascx” User Control
3. Access custom property from the User Control

1. Add a custom property in “VisualWebPart1.cs” Web Part class

My custom property will be an enum value to select control mode between Simple, Standard and Advanced.

public enum ControlModes
{
Simple,
Standard,
Advanced
}

/// <summary>
/// This property will be displayed as a drop-down list in the property pane.
/// </summary>
[DefaultValue(ControlModes.Standard)]
[Description("Select a category from the dropdown list.")]
[WebBrowsable(true)]
[Personalizable()]
public ControlModes ControlMode
{
get; set;
}

These custom properties will be displayed in the property pane as different controls according to the type of the property.

• bool -> Check box
• enum -> Dropdown list
• int -> Text box
• string -> Text box
• DateTime -> Text box

In here this property will be rendered as a Dropdown list since it is enum type. I can specify a default value and a description for this property, which are optional. Then “WebBrowsable” attribute is used to tell that this property should be displayed in the property pane. Then “Personalizable” attribute tells to store the value of this property in the database, so it will retain in the next time.

2. Make custom property visible to “VisualWebPart1UserControl.ascx” User Control

Here we need to change “CreateChildControls” method implementation of the “VisualWebPart1.cs” class to pass the value of our custom property to the User Control. Here if we pass the WebPart class itself as a property, we can simply access several custom properties by less code.

User Control Property

public VisualWebPart1 WebPartControl { get; set; }

“CreateChildControls” in “VisualWebPart1.cs”

protected override void CreateChildControls()
{
VisualWebPart1UserControl control = Page.LoadControl(_ascxPath) as
 VisualWebPart1UserControl;
if (control != null)
{
   control.WebPartControl = this;
}
Controls.Add(control);
}

3. Access custom property from the User Control

public VisualWebPart1.ControlModes ControlMode
{
get
{
   return this.WebPartControl.ControlMode;
}
}

Once deployed and added this Web Part to a page, we can go to Web Part properties by selecting “Edit Web Part” option.

We can see our custom property in the Property Pane under “Miscellaneous” section. Description attribute we added can be seen as a tooltip here.

Here is my complete code for “VisualWebPart1.cs” Web Part class and “VisualWebPart1UserControl.ascx” User Control.

VisualWebPart1.cs

using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

namespace CustomProperty.VisualWebPart1
{
[ToolboxItemAttribute(false)]
public class VisualWebPart1 : WebPart
{
   // Visual Studio might automatically update this path when you change the
   // Visual Web Part project item.
   private const string _ascxPath = 
     @"~/_CONTROLTEMPLATES/CustomProperty/VisualWebPart1/
          VisualWebPart1UserControl.ascx";

   public enum ControlModes
   {
       Simple,
       Standard,
       Advanced
   }

   /// <summary>
   /// This property will be displayed as a drop-down list in the
   /// property pane.
   /// </summary>
   [DefaultValue(ControlModes.Standard)]
   [Description("Select a category from the dropdown list.")]
   [WebBrowsable(true)]
   [Personalizable()]
   public ControlModes ControlMode
   {
       get;
       set;
   }

   protected override void CreateChildControls()
   {
       VisualWebPart1UserControl control = Page.LoadControl(_ascxPath) as
         VisualWebPart1UserControl;
       if (control != null)
       {
           control.WebPartControl = this;
       }
       Controls.Add(control);
   }
}
}

VisualWebPart1UserControl.ascx

using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;

namespace CustomProperty.VisualWebPart1
{
public partial class VisualWebPart1UserControl : UserControl
{
   public VisualWebPart1 WebPartControl { get; set; }

   public VisualWebPart1.ControlModes ControlMode
   {
       get
       {
           if (this.WebPartControl != null)
           {
               // User selected value.
               return this.WebPartControl.ControlMode;
           }
           else
           {
               // Default value.
               return VisualWebPart1.ControlModes.Standard;
           }
       }
   }

   protected void Page_Load(object sender, EventArgs e)
   {
   }
}
}

Note: If the default Web Part property pane is not good enough to display our custom property, we can create a custom user interface called a “Tool Part” for the purpose.