SharePoint 2007 has built in pop-up pickers for selecting lists and sites as used in the Context Quey web part, however these are not automatically exposed to other web parts. Web parts which operate on list data often need to be able to allow users to select one or more lists or sites via their tool panes. Ideally, the default tool part would recognise SPSite and SPList properties and provide pop-up pickers automatically. Sadly this is not the case. However, it is still possible to leverage most functionality used by built in web parts such as the Content Query Web Part from your own custom tool pane.

Essentially what we’re going to do is create a tool part which is generic enough to be bound to any web part and allow selection of lists and sites using the built in picker functions in PickerTreeDialog.js. When completed simply overriding the GetToolParts method in your web part will be enough to create an extra tool part with as many list or site selectors as are required.

public override ToolPart[] GetToolParts()
{
    List<ToolPart> parts = new List<ToolPart>();
    PickerToolPart picker = new PickerToolPart();

    parts.AddRange(base.GetToolParts());

    picker.Items.Add(new PickerItem("Site to query", "TargetURL", PickerType.Site));
    picker.Title = "Select data source";
    parts.Add(picker);

    return parts.ToArray();
}

In the example above we are mapping two custom properties- TargetURL and ListURL- to a site picker and list picker respectively. We are also retaining all other default tool parts because the generic PickerToolPart class we are going to write only deals with selection of sites and lists. Because we are retaining the default tool parts though we need to be careful to mark the properties we are setting with the Browsable(false) attribute to ensure that they do not appear twice (i.e. as a normal text box and as our custom picker).

[Browsable(false), Category("Miscellaneous"), DefaultValue(""),
WebPartStorage(Storage.Shared)]
public string TargetURL
{
    get;
    set;
}

First we need to create a PickerItem class. When the tool pane is set up, an instance of PickerItem is created for each mapping of a list or site to a property. These are passed into the Items collection of our PickerToolPart. The PickerItem class is accompanied by an enumeration which is used to determine which type of object (site or list) is being selected.

public enum PickerType
{
    Site,
    List
}

public class PickerItem
{
    public string Title { private set;  get; }
    public string PropertyName { private set; get; }
    public PickerType PickerType { private set; get; }

    public PickerItem(string title, string propertyName, PickerType pickerType)
    {
        Title = title;
        PropertyName = propertyName;
        PickerType = pickerType;
    }
}

Next we create our custom tool pane PickerToolPart. This tool part simply creates a text box and a button for each of the PickerItem instance in it’s Items collection. The button is used to call the built in SharePoint picker windows to allow the user to select a list or site. Once a selection has been made the associated text box is populated with the URL of the selected item.

public class PickerToolPart : ToolPart, INamingContainer
{
     public List<PickerItem> Items { get; set; }

    /// <summary>
    /// Initializes a new instance of the <see cref="PickerToolPart"/> class.
    /// </summary>
    public PickerToolPart()
        : base()
    {
        Items = new List<PickerItem>();
    }

    /// <summary>
    /// Registers the script to load the web selector.
    /// </summary>
    void RegisterPopupScript()
    {
        StringBuilder sb = new StringBuilder();
        sb.Append("function cust_launchPickerSite(inputID)\r\n {\r\n  if (!document.getElementById) return;");
        sb.Append("var targetTextBox = document.getElementById(");
        sb.Append("inputID");
        sb.Append(");");
        sb.Append("if (targetTextBox == null) return;");
        sb.Append("var serverUrl = '");
        sb.Append(SPContext.Current.Web.ServerRelativeUrl);
        sb.Append("';var callbackSite = function(results){if (results == null || results[1] == null) return;targetTextBox.value = results[1];};\r\n");
        sb.Append("LaunchPickerTreeDialog('CbqPickerSelectSiteTitle','CbqPickerSelectSiteText','websOnly','',serverUrl, '','','','/_layouts/images/smt_icon.gif','', callbackSite);}");
        this.Page.ClientScript.RegisterClientScriptBlock(typeof(PickerToolPart), "PickerSite", sb.ToString(), true);

        sb = new StringBuilder();
        sb.Append("function cust_launchPickerList(inputID)\r\n {\r\n  if (!document.getElementById) return;");
        sb.Append("var targetTextBox = document.getElementById(");
        sb.Append("inputID");
        sb.Append(");");
        sb.Append("if (targetTextBox == null) return;");
        sb.Append("var serverUrl = '");
        sb.Append(SPContext.Current.Web.ServerRelativeUrl);
        sb.Append("';var callbackList = function(results){if (results == null || results[1] == null || results[2] == null) return;targetTextBox.value = results[1]+(results[1]=='/' ? '' : '/')+results[2];};\r\n");
        sb.Append("LaunchPickerTreeDialog('CbqPickerSelectListTitle','CbqPickerSelectListText','listsOnly','',serverUrl, '','','','/_layouts/images/smt_icon.gif','', callbackList);}");
        this.Page.ClientScript.RegisterClientScriptBlock(typeof(PickerToolPart), "PickerList", sb.ToString(), true);

        this.Page.ClientScript.RegisterClientScriptInclude("PickerTreeDialog", "/_layouts/1033/PickerTreeDialog.js");
    }

    /// <summary>
    /// Raises the <see cref="E:System.Web.UI.Control.Load"/> event.
    /// </summary>
    /// <param name="e">The <see cref="T:System.EventArgs"/> object that contains the event data.</param>
    protected override void OnLoad(EventArgs e)
    {
        base.OnLoad(e);
        RegisterPopupScript();
    }

    /// <summary>
    /// Gets a property value of an object by reflection.
    /// </summary>
    /// <param name="target">Target object.</param>
    /// <param name="name">Name of the property.</param>
    /// <returns>The property value.</returns>
    object GetPropertyValue(object target, string name)
    {
        try
        {
            PropertyInfo pi = target.GetType().GetProperty(name);
            return pi.GetValue(target, null);
        }
        catch
        {
            return "##error##";
        }
    }

    /// <summary>
    /// Sets a property value of an object by reflection.
    /// </summary>
    /// <param name="target">Target object.</param>
    /// <param name="name">Name of the property.</param>
    /// <param name="value">The value to set.</param>
    /// <returns>The property value.</returns>
    void SetPropertyValue(object target, string name, object value)
    {
        PropertyInfo pi = target.GetType().GetProperty(name);
        pi.SetValue(target, value, null);
    }

    /// <summary>
    /// Sends the tool part content to the specified HtmlTextWriter object, which writes the content to be rendered on the client.
    /// </summary>
    /// <param name="output">The HtmlTextWriter object that receives the tool part content.</param>
    protected override void RenderToolPart(HtmlTextWriter output)
    {
        WebPart parent;
        int i = 0;

        parent = this.ParentToolPane.SelectedWebPart;

        if (Items.Count > 0)
        {
            output.Write("<table cellspacing=\"0\" border=\"0\" style=\"border-width:0px;width:100%;border-collapse:collapse;\">");

            foreach (PickerItem pi in Items)
            {
                output.Write("<tr><td>");
                output.Write("<div class=\"UserSectionHead\">");
                output.Write(pi.Title);
                output.Write("</div>");
                output.Write("<div class=\"UserControlGroup\"><nobr>");
                output.Write("<input type=\"text\" ");
                output.Write("value=\"" + GetPropertyValue(parent, pi.PropertyName) + "\"");
                output.Write(" name=\"picker_" + i.ToString() + "\" id=\"picker_" + i.ToString() + "\"/>");
                output.Write("<input type=\"button\" onclick=\"" + (pi.PickerType == PickerType.Site ? "cust_launchPickerSite" : "cust_launchPickerList"));
                output.Write("('picker_" + i.ToString() + "'); return false;\" value=\"...\"/>");

                output.Write("</nobr></div>");
                output.Write("</td></tr>");
                i++;
            }

            output.Write("</table>");
        }
    }

    /// <summary>
    /// Called when the user clicks the OK or the Apply button in the tool pane.
    /// </summary>
    public override void ApplyChanges()
    {
        WebPart parent;
        int i = 0;

        parent = ParentToolPane.SelectedWebPart;

        if (Items.Count > 0)
        {
            foreach (PickerItem pi in Items)
            {
                SetPropertyValue(parent, pi.PropertyName, Page.Request.Form["picker_" + i.ToString()]);
                i++;
            }
        }
    }
}

The tool part notifies the parent web part of changes when the OK or Apply button is clicked through the ApplyChanges method. Reflection is used to set the properties named in each PickerItem object. The resulting view looks similar to the following.

Clearly providing this kind of selector in your custom web parts helps to make them more user friendly and doesn’t really take all that much effort. I do think though that more of the built in types such as SPSite and SPList should be inherently supported by the built in tool part editors. Maybe in the next version! Note though that this code sample only works with SharePoint 2007 (not WSS) as PickerTreeDialog.js is not included with WSS.