Web Part Properties

Properties of a Web Part

A Web Part class can contain properties which can be edited in the web interface or application development environment. To be editable the property has to be marked with a set of attributes which specifies how and who can edit the property.

Note: When creating editable properties for your Web Part you have to create properties that are read/write, public and called without parameters.

sample Web Part needs four properties to work;

  • Display mode – an enumeration on what type of tweets to show
  • User name – a string, if the user time line mode is chosen
  • Search text – a string, if the Twitter search mode is chosen
  • Tweet Count – the number (integer) of tweets to show
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

If you want all of these four properties to appear when someone modifies the Web Part, so you have to mark all four of these properties as WebBrowsableThis indicates to SharePoint that the property can be edited in the web the tool pane. The system will take care of how the user interface will look like; strings will be text boxes, booleans will be check boxes, enumerations will be dropdowns etc.

To make the properties appear there is one more thing you have to do, you have to add the Personalizable attribute and set the personalization scope. This attribute tells the Web Part Manager that this property value is persisted. If you set the scope to User (default), then users (Members) can modify this property and if it’s set toShared only editors (Owners) are allowed to change the property.

Tip: If you omit “Personalizable” attribute, you cannot change it through the web interface, only through code or tools such as SharePoint Designer. This might be a preferred solution in some cases.

This will make your custom tool pane look like this:

Custom property

Now things work, you can edit and save the value of the property and it is stored in SharePoint. But to further enhance the editing experience you should make it more user friendly.

Make the tool pane more user friendly

You should give it a name and a description, shown as a tooltip, to show in the editing tool pane that are more user friendly than the name of the property. Don’t rely on that your users or administrators interpret your property names correct. This is done with the WebDisplayName and WebDescription attributes.

The tool pane has a set of categories (AppearanceAdvanced and Layout) which are reserved for the base class properties. The custom properties will end up in a category called Miscellaneous, if you do not provide your own category with the Category attribute.

NOTE: To use Category attribute, you must include “System.ComponentModel” to the web part *.cs file

Note: You cannot add properties to the reserved categories.

[WebBrowsable]
[WebDisplayName("User name")]
[WebDescription("The Twitter Username")]
[Category("Twitter")]
[Personalizable(PersonalizationScope.User)]
public string Username {
    get;
    set;
}

This property now has a friendly name and a description, it’s located under the Twitter category and users can change the value of it, and have their own values.

Note: If you make changes to it in the Shared view, default if you are an admin, it will be the default values for users who have not personalized the Web Part.

The same is done for the other three properties and now the Twitter category looks like this when editing the Web Part:

Shared tool pane view of TweetPart

Shared only properties and storage

I want the Tweet count property to be edited only by those who are allowed to edit the Shared view of the web part, therefore I change the PersonalizationScope of the Personalizable attribute to Shared. This means that this property will not be displayed when editing the personal (My) view of the Web Part.

I also add and specify the WebPartStorage attribute to Shared, this makes the Web Part store only one set of value for this property. Default is the Personal storage mode, which means that every user has it’s own property value.

Tip: If you set the storage to Shared and personalization scope to User then every user can edit the same (shared) value.

NOTE: To use WebPartStroage attribute, you must include “Microsoft.SharePoint.WebPartPages” to the web part *.cs file

Now this property looks like this:

[WebBrowsable]
[WebDisplayName("Tweet count")]
[WebDescription("Number of tweets to show")]
[Category("Twitter")]
[Personalizable(PersonalizationScope.Shared)]
[WebPartStorage(Storage.Shared)]
public int TweetCount {
    get;
    set;
}

if you now open up the shared properties of the Web Part, then it looks the same as above, but if you instead go to the personal view then it looks like this:

Personal tool pane view of TweetPart

As you can see there is no Tweet Count property to edit, it’s only available in shared mode.

Tip: To switch between Shared and Personal mode just add this parameter to the query string PageView=[Shared|Personal].

I prefer to have a nice message and a hyperlink that the user can click which opens up the tool pane immediately like this:

Sample

Now all the user have to do is click the link and fill in the appropriate values.

The code for this simple Web Part looks like this:

  1: protected override void CreateChildControls() {
  2:     if (string.IsNullOrEmpty(this.Text)) {
  3:         LiteralControl literalCtrl = new LiteralControl(
  4:             string.Format("<a id='MsoFrameworkToolpartDefmsg_{0}' href=\"javascript:MSOTlPn_ShowToolPane2Wrapper('Edit','129','{0}');\">Open the tool pane and enter a valid value.",
  5:             this.ID));
  6:         Controls.Add(literalCtrl);
  7:     }
  8:     else {
  9:         Label lblHello = new Label();
 10:         lblHello.Text = "Hello " + this.Text;
 11:         Controls.Add(lblHello);
 12:     }
 13: }

This code creates a hyperlink which uses one of SharePoint’s built-in JavaScripts which opens the tool pane.

Cited: http://www.wictorwilen.se/

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s