SharePoint 2013 - Configurable Web Part Properties

In this post we will discuss about web part properties and how to create configurable web part properties.

WebPart Properties
All Web Parts share a set of common properties that allow you to specify attributes for the appearance, layout, and other information. To view web part properties, click on the web part menu and select Edit web part".

On the right hand side you can see the web part properties window opens. Here you can make the basic changes like adjusting height, width, Title, etc.

Configurable WebPart Properties
Apart from the default properties, you may want to add you own custom properties which can be even used as parameters for the webpart. Configurable Web Parts are used to present a user-friendly interface for Web Parts configuration. The following attributes makes it possible to add custom properties.

The WebBrowsableAttribute class

The WebBrowsableAttribute class instructs the Web Parts infrastructure that the property has to be made available in the Web Part’s configuration panel. 

The PersonalizableAttribute class

The PersonalizableAttribute declares that the property can be personalized and defines the scope of the personalization. There 2 types of scopes:

1) Scope of type User, which means that the property can be personalized on a per-user basis.

2) Scope of type Shared, which means that the property personalization will be shared between all users.

Configurable WebPart Attributes
Following attributes enables the display of the custom properties in web part properties window.

1) [WebBrowsable(true)] - This will hide or show the property on the tool pane.

2) [Personalizable(PersonalizationScope.Shared)] - How the WebPart is configured, which can be per-user (PersonalizationScope.User), or for everyone (PersonalizationScope.Shared). 

3) [WebDescription("Description of List")] - Description for the property.

4) [WebDisplayName("My List Name")] - Label for the property.

5) [Category("Personalized Items")] - This will group your property according to category. If not declared, “Miscellaneous” will be used as the default.

6) [DefaultValue("Default")] - The default value for the property.

Creating a Configurable Web Part Property

For a better understanding, lets modify the Visual web part we created in the previous post and add a configurable web part property. In the previous post we created a visual web part to show items in "Products" List. Now we will add a custom web part property to accept List name as a parameter and display the items for that specific list.

Following are the steps:

1) Create a 2 custom list named "Products" and "Customers" with columns and data of your choice. 

2) Create a new visual web part following the steps as mentioned in the previous post.

(http://sptechbytes.blogspot.in/2013/10/sharepoint-2013-creating-visual-webpart_26.html)

Code Snippet

35. protected void Page_Load(object sender, EventArgs e)
36.         {
37.             if (this.ListName != null && this.ListName.Trim()!="")
38.             {
39.                 SPSite oSite = SPContext.Current.Site;
40.                 using (SPWeb oWeb = oSite.OpenWeb())
41.                 {                    
42.                     SPList oList = oWeb.Lists["Products"];
43.                     SPListItemCollection oColl = oList.GetItems();
44.                     gvwProducts.DataSource = oColl.GetDataTable();
45.                     gvwProducts.DataBind();
46.                 }
47.             }
48.         }

3) Create a new property named ListName in the visual webpart class as follows and add the WebBrowsable attribute to it:

Code Snippet

28. [WebBrowsable(true),
29. Category("Personalize"),
30. WebDisplayName("List Name"),
31. WebDescription("Custom list name editable by user")]
32. [Personalizable(PersonalizationScope.Shared)]
33. public string ListName { get; set; }

3)  Modify the code inside the Page_Load method as follows. The ListName property will be passed as parameter for getting the data from the specified list and display in a grid-view.

Code Snippet

35. protected void Page_Load(object sender, EventArgs e)
36.         {
37.             if (this.ListName != null && this.ListName.Trim()!="")
38.             {
39.                 SPSite oSite = SPContext.Current.Site;
40.                 using (SPWeb oWeb = oSite.OpenWeb())
41.                 {                    
42.                     SPList oList = oWeb.Lists[this.ListName];
43.                     SPListItemCollection oColl = oList.GetItems();
44.                     gvwProducts.DataSource = oColl.GetDataTable();
45.                     gvwProducts.DataBind();
46.                 }
47.             }
48.         }

4) Deploy the solution and open the web part page in edit mode. Go to the web part properties and you can see the new custom property that we added. Enter the list name "Products" and click "Apply" button, you will see the items in the Products List are populated in the GridView.

5) Now change the List Name to "Customers" and click "Apply" button. 

6) You will see the items in the "Customers" list will be populated in the GridView.

Note:- The above code defined property that requires the end user to configure the Web Part manually, typing the target list name autonomously and  made use of the standard behaviour of SharePoint and the out-of-the-box CustomPropertyToolPart.

But this is not a user-friendly and error-free approach. The right solution would probably be to provide a drop-down list with all the lists available in the current website, thereby avoiding typo errors and the consequent time consuming debugging tasks.
To customize the Web Parts’ configuration user interface you can create custom classes called "Editor Parts" which are controls hosted in a specific WebPartZone called EditorZone.

We will take a closure look on to Editor Parts in the next post.