Adding a ToolPane Opener to a WSSv3 ASP.NET Web Part

[CORRECTION/UPDATE: September 2007] You should always inherit from the ASP.NET WebPart class. You should never EVER use Microsoft.SharePoint.WebPartPages.WebPart. NEVER. EVER. The correct method to use to get the tool panes for ASP.NET Web Parts is "CreateEditorParts".

A nice touch in custom web parts is a link to initialize the web part. A good example of this is the content editor web part– add one to your page and you’ll get a friendly message, "To add content, open the tool pane and then click Rich Text Editor." This is relatively easy to do using the ToolPane.GetShowToolPaneEvent method. Unfortunately, this method expects a Microsoft.SharePoint.WebPartPages.WebPart, and the desired base class for v3 development is the ASP.NET WebPart. (Note that this is still an issue for B2TR– but I doubt Microsoft will fix this for RTM.)

Luckily, ToolPane has another method called "GetShowExtensibleToolPaneEvent" that does almost what we want, and takes the webpart ID as the argument. The link that it passes back though opens the ExtensibleView of the web part– and I’m not sure how to get at that, it’s a blank toolpane window that would be cool to use but I’m not sure how. (If you know how, please share that info with me!) But simply replacing the javascript argument "ExtensibleView" with the argument "Edit" will do the trick.

Incorporating the previous security code example, here’s a Web Part method (safe for a System.Web.UI.WebControls.WebParts.WebPart or a SharePoint WebPart) that adds a control to open the SharePoint toolpane if the user has the correct rights.

/// <summary>
/// Adds a control to initialize the WebPart.
/// </summary>
protected void AddInitializeControl()
{
  bool hasRights = ((ISecurableObject)SPContext.Current.Web).DoesUserHavePermissions((SPBasePermissions)Microsoft.SharePoint.SPPermissionGroup.WebDesigner);

  if (!hasRights)
    return;

  string editLink = Microsoft.SharePoint.WebPartPages.ToolPane.GetShowExtensibleToolPaneEvent(string.Format(@"’{0}’",this.UniqueID));
  this.Controls.Add(new LiteralControl(
    string.Format(@"<br/><a href=""javascript:{0}"">Initialize WebPart</a><br/>",
    editLink.Replace(@"ExtensibleView", @"Edit"))
  ));
}

—————–

UPDATE:

The supported way to add custom toolpanes to the ASP.NET WebPart class is through implementing the ICustomizeToolPane interface, with a method like the following. HOWEVER– this is buggy, and throws an InvalidOperationException from the ASP.NET WebPart. Also of note, unless you tweak the verb menu, this will be a different toolpane view than the EditWebPart view. Regardless, here’s the syntax:

public void CreateToolPaneControls(Microsoft.SharePoint.WebPartPages.ToolPane toolpane)
{
  LocationEditorPart locEditor = new LocationEditorPart(this);
  toolpane.InsertToolPart(0, locEditor);
  Microsoft.SharePoint.WebPartPages.WebPartToolPart standardToolPart = new Microsoft.SharePoint.WebPartPages.WebPartToolPart();
  toolpane.InsertToolPart(1, standardToolPart);
}

So in the meantime– and in case this doesn’t change before WSSv3 RTM, it seems the only supported way to implement custom tool panes is to implement from the Microsoft.SharePoint.WebPartPages.WebPart and override the GetToolParts method, like so:

public override Microsoft.SharePoint.WebPartPages.ToolPart[] GetToolParts()
{
  List<ToolPart> parts = new List<ToolPart>();
  parts.AddRange(base.GetToolParts());
  parts.Insert(0, new LocationEditorPart(this));
  return parts.ToArray();
}

So while the documents say "you should design Web Parts that inherit from the ASP.NET 2.0 System.Web.UI.WebControls.WebParts.WebPart base class whenever possible", you really need to inherit from the Windows SharePoint Services WebPart class if you’re doing anything interesting with the SharePoint tool pane. This does affect the DWP/WebPart file, as the .webpart file is incompatible with the SharePoint WebPart which must use the .dwp file. However, I still use my favorite tool for the webpart galley (instead of hand-writing the dwp): http://localhost/_catalogs/wp/Forms/AllItems.aspx and  http://localhost/_layouts/NewDwp.aspx.