Customizing SharePoint Web Parts with Custom Properties

By Gayan Peiris

Developers have the flexibility to create custom Web Parts to achieve sophisticated custom functionality in SharePoint Portal server. Typically this will be used to create common customized functionality for a specific organization or project. There are several properties available by default from SharePoint Portal server to customize the Web Part. Alternatively, developers can create their own custom properties to achieve extra customization on Web Part appearance and behavior.

Properties

The Web Part base class provides a set of default properties which allow users to change appearance and behavior. These properties are found in the default Web Part property pages and contain basic customization properties, such as height, width, frame set state and much more (as illustrated below).

Figure 1: Properties available by default in the “default” property pane.

TIP: To access the property pane, select the Edit mode of the Web Part. Then click the down arrow located at top right hand corner of the Web Part. Select “Modify Shared web part” (or personnel depend on witch mode the Web Part is running).

The properties are categorized according to their behavior and functionality, which provides a logical structure when you need to find the right item. According to Figure 1, all the properties that affect appearance are listed below the “Appearance” category and all the advanced options under the “Advanced” category.

While the default properties are a good starting point, it won’t take long until you come across development requirements which the default properties cannot satisfy. This is where you implement Custom Properties to achieve the additional functionality or behavior required.

Custom Properties

A Custom Property is a property that a developer creates when they need to introduce additional functionality or behavior to the Web Part that is not provided by the base class.

The Visual Studio .Net environment supports the development of Web Parts for SharePoint Portal Server. The Web Part Template provided on MSDN (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odc_sp2003_ta/html/sharepoint_webparttemplates.asp)
provides an excellent starting point with the structure of a custom Web Part property (example below).

///<summary>

/// Default property
available form the template

///</summary>

[Browsable(true),Category("Miscellaneous"),

DefaultValue(defaultText),

WebPartStorage(Storage.Personal),

FriendlyName("Text"),Description("Text
Property")]

publicstring Text

{

get

{

return text;

}

set

{

text
= value;

}

}

Figure 2: Default custom property available from MSDN template.

Before we start developing any custom properties, let’s have a look at how custom property works. The custom properties can be customized and saved in SharePoint as XML. The System.Xml.Serialization namespace is used to serialize the Custom Properties to XML. The above namespace will be available from System.Xml.dll assembly. There is a XML namespace attribute defined at the root level of the assembly as displayed below,

///<summary>

/// Customize a web part

///</summary>

[DefaultProperty("Text"),

ToolboxData("<{0}:CustomizedWebPart runat=server></{0}:CustomizedWebPart>"),XmlRoot(Namespace="CustomizedWebPart")]

publicclass Customer
: Microsoft.SharePoint.WebPartPages.WebPart

{

Figure 3: XML namespace in root level

The namespace attribute can be defined, either at the root level or at the property level. If a root level XML namespace is available, the developer doesn’t need to assign XML namespaces at property level. But if the developer assigns a XML namespace at the property level, this will override the XML namespace assigned at the root level.

If you are using the template provided by MSDN, the System.Xml.dll will be automatically added to your reference in Web Part project as display below,

Figure 4: System.Xml.dll in Web Part project reference list

There are two parts to create a Custom Property:

1. Create property accessors

Each Custom Property of the Web Part requires the appropriate get and set accessors methods.

publicstring Text

{

get

{

return text;

}

set

{

text
= value;

}

}

Figure 5: Get and Set accessors methods for a Web Part property in C#

2. Set Web Part Property attributes

Most attributes are members of the System.ComponentModel namespace. This namespace provides the classes that are used to implement the run time and design time behavior for Microsoft .NET components and controls. At the same time, there are properties like WebPartStorage attribute, which are specifically designed for Web Part properties. The attributes that you specify for the custom property will determine the behavior of the Web Part in the property pane and determine the storage for the custom property. Following is a list of attributes available and how they affect the behavior of the property.

• Browsable
  Determines whether or not the property is visible in the property pane or not. Setting this attribute to true will include the property.

• Category
  The property pane is divided into sections. This attribute determines the name of the section in the property pane where the custom property will be displayed. This allows the developer to categories their custom properties according to their logical functionality. If the developer does not specify this attribute or select “Default” as the category, the custom properties will display in Miscellaneous section of the property pane. At the same time, if you select one of the default categories, such as Appearance, Layout or Advanced, the category attribute setting will be ignored and the property will displayed in Miscellaneous section.

• Default Value
  This is the default value of the property. It will minimize the storage requirement by storing the property value only if it is different from the default value.

• Description
  Additional information regarding the property for the end-user. The description appears as the tool tip when the mouse hovers over the property.

• FriendlyNameAttribute
  This is the caption of the property when it is displayed in the property pages. If this attribute is omitted, the actual name of the property is used instead.

• ReadOnly
  The custom property will be read only if this is set to true.

• WebPartStorage
  There are three settings for this attribute.
  • Storage.Shared: Display in property pane when the user is in shared view of the page.
  • Storage.Personal: Displays when the user is in shared OR personal view of the page.
  • Storage.None: Does not persist the setting of the property and will not display in the property pane.

Properties will display in different formats according to the property type. (as displayed below)