HtmlDesignerAttribute: Custom Property Builders for SharePoint Web Parts

There are occasions when it may be necessary to provide web part users with a richer interface for setting custom properties than SharePoint provides out-of-the-Box. By using the HtmlDesignerAttribute and a little bit of Javascript, we can provide web part users with a custom property builder which presents a stylish and functional interface to manage custom web part properties.

Microsoft provides us with a simple example custom property builder in the zoombldr.aspx file located below the 60 hive in C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\LAYOUTS\[LCID] where LCID equals 1033 for English - United States installations. Zoombldr.aspx is displayed by clicking the small button that appears to the right of a text property in a web part's toolpart:

If we take a look behind the scenes, we'll see that the OnClick event of the text property's button in the tool part calls out to the Javascript function MSOPGrid_doBuilder(). MSOPGrid_doBuilder() is located in the ows.js file, and looks like this (click for larger view):

As you can see, MSOPGrid_doBuilder() makes a Javascript showModalDialog() call with parameters to indicate the location of the page to be displayed, the arguments to pass to the dialog window, and settings for the dialog window's appearance.

To use our own custom builder, we start by decorating the web part custom property in question with the HtmlDesignerAttribute as shown below:

The BrowserBuildertype.Dynamic parameter of the HtmlDesignerAttribute also requires us to override the GetCustomerBuilder method of Microsoft.SharePoint.WebPartPages.WebPart in our web part class:

Inside of your custom builder page, get hold of the web part's property value by accessing the Javascript window.dialogArguments object. Subsequently, your custom builder can manipulate and ultimately return the web part's property value through the window.returnValue object. A good practice for getting and setting the values of these Javascript objects is by overriding the window.onload and window.onunload events:

Finally, here's an example of a custom property builder in action:

There seems to be very little doumentation on the HtmlDesignerAttribute, and Googling for 'HtmlDesignerAtribute' produces only a few results, of which only one or two are actually useful. There's also an interesting BuilderArguments parameter to the HtmlDesignerAttribute that I'm not even sure what does! The docs say that BuilderArguments "Contains the arguments that are passed to the custom builder" but nothing appears to be passed into the window.dialogArguments object from this parameter (any ideas?).

This article has skimmed over a lot of the details, assuming that you have some experience in developing custom web parts. For further study, I'd recommend starting off by dissecting the zoombldr.aspx file and experimenting a bit on your own. If you'd like to to learn more about developing web parts and other solutions for Windows SharePoint Service and SharePoint Portal Server 2003, please consider attending one of our developer classes.