Leveraging Custom Property Builders in SharePoint Web Parts

A few months ago, I posted an article about decorating your custom SharePoint web part's properties with the HtmlDesignerAttribute to provide users with a richer, more functional interface for setting custom web part properties. These specialized user interfaces for setting web part properties are called Custom Property Builders.

While it is possible to create your own Custom Property Builders, there are several Custom Property Builders provided with SharePoint out-of-the-box. In this article, I'll take a few moments to expand on a few of the Custom Property Builders that come with SharePoint, and review how to leverage these Custom Property Builders in your own Web Parts.

To begin with, here's a table with some (not all!) of the Custom Property Builders that are installed with SharePoint. A few are specific to SharePoint Portal Server, and others come with Windows SharePoint Services.

Location	Function
_layouts/1033/Audience_Chooser.aspx	Audiences Picker
_layouts/1033/CategoryPickerPopUp.aspx	Areas Picker
_layouts/1033/PickerContainer.aspx	Select Users, Distribution Lists, and Security Groups
_layouts/1033/zoombldr.aspx	Basic Text Editor

One of the simplest Custom Property Builders to use is zoombuilder.aspx, which provides a basic text editor for setting a string-based web part custom property.

Communication with the Custom Property Builder from you web part's code is done through a hidden form field. This hidden form field is used to pass data into and receive output back from the Custom Property Builder. Place the code to create this hidden form field in the overridden OnPreRender() method of the Tool Part.

protected override void OnPreRender(EventArgs e)
{

base.OnPreRender(e);
if(Page != null)
{

// Get the calling Web Part's Instance
WebPart1 wp = new WebPart1();
wp = (WebPart1)this.ParentToolPane.SelectedWebPart;
// Get the value for the custom web part property
string parameters = wp.Text;
// Create a unique identifier for the hidden form field
string uniqueId = "MyCustomProperty" + this.UniqueID.Replace(":","_");
// Place hidden form field on the page
Page.RegisterHiddenField(uniqueId, parameters);

}

}

You’ll want to have the property value change take effect as soon as the Customer Property Builder is closed. To do this, you’ll need to programmatically “click the Apply button”. Here’s the JavaScript function to click the Apply button, which should also be placed in the Tool Part’s overridden OnPreRender() method.

string shortId = this.UniqueID.Substring(0,this.UniqueID.IndexOf(":"));
string EmbeddedScriptFormat = "<script language=jscript>function ApplyProperties(){\n";
EmbeddedScriptFormat += "document.forms[MSOWebPartPageFormName].MSOTlPn_Button.value = 'apply';\n";
EmbeddedScriptFormat += "document.forms[MSOWebPartPageFormName].elements['" + shortId + ":MSOTlPn_AppBtn'].click();\n";
EmbeddedScriptFormat += "}\n";
EmbeddedScriptFormat += "</script>\n";
if(!Page.IsClientScriptBlockRegistered(“applyFunction”))
Page.RegisterClientScriptBlock(“applyFunction”, EmbeddedScriptFormat);

Now, to Apply the return value of the Custom Property Builder to your web part property, place the necessary code in the Tool Part's overridden ApplyChanges() method. The ApplyChanges() method will be called after you programmatically “click the Apply Button”.

public override void ApplyChanges()
{

// Get the calling Web Part's Instance
WebPart1 wp = new WebPart1();
wp = (WebPart1)this.ParentToolPane.SelectedWebPart;
// Create a unique identifier for the hidden form field
string uniqueId = "MyCustomProperty" + this.UniqueID.Replace(":","_");
// Set the web part property with the value from the hidden field
wp.Text = this.Context.Request.Params[uniqueId];

}

Launching the Custom Property builder from your custom Web Part's Tool Part is done through JavaScript. SharePoint provides a JavaScript Method for doing this called MSOPGrid_doBuilder(). For your reference MSOPGrid_doBuilder() is located in the ows.js file. MSOPGrid_doBuilder() takes as parameters the path to a Custom Property Builder's location, the Element ID for the hidden form field, and some details on how to the display the Custom Property builder's dialog window. You'll want to call MSOPGrid_doBuilder() from the OnClick event of an element in the Tool Part. This snippet is from the CreateChildControls() method of a Tool Part.

string designerUrl = "_layouts/1033/zoombldr.aspx";
string designerProperties = "dialogHeight:510px;dialogWidth:560px;help:no;status:no;resizable:yes";
string uniqueId = "MyCustomProperty" + this.UniqueID.Replace(":","_");
Label lbl = new Label();
// Client-side button click handler
string onClick = "MSOPGrid_doBuilder('" + designerUrl + "', " + uniqueId + ", '" + designerProperties + "');ApplyProperties();";
lbl.Attributes.Add("OnClick", onClick);

That's about it for handling how to launch a Custom Property Builder and passing data to/from your web part. The zoombldr.aspx is about the simplest Custom Property Builder, using just an regular text string for input and output. Other Customer Property Builder will use comma delimited strings of data for input/output. For example, Audience_Chooser.aspx takes and returns a list of Audience GUIDs e.g. 'E76ADC57-C430-4464-AFA0-028A625D5C2D','332F0A00-55ED-4ae3-BCE3-9B465B675E6F','53C26C1D-4422-4625-BA94-6DCB63F4800E'.

With a bit of reverse engineering you can figure out how to use each of the Custom Property Builders. As further reading, here's a post from SharePoint MVP Gary Bushey that covers using the PickerContainer.aspx Custom Property Builder to select Users, Distribution Groups, and Security Groups from AD.

To wrap up, here are some screenshots for a few of the Custom Property Builders installed with SharePoint: