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)
| Property Type | Display as |
| Bool | Check box |
| DateTime | Text box |
| Enum Drop | down box |
| int / string | Text box |
• Code Example >>
