Create a Custom Picker in SharePoint 2010


Introduction

 

One of SharePoint’s neatest features is the People Picker. It allows a SharePoint user to elegantly query, identify and select SharePoint accounts. Did you know the People Picker is built on a set of publically available picker controls available to every SharePoint developer? Read the rest of this article to find out how to include a custom picker into your new SharePoint application.

Cast of Characters

Developing a custom SharePoint picker involves the creation and orchestration of three components, the Editor, Picker Dialog and the Query.

Editor

The editor provides an entry point for the user to express the selected entities. It also provides a launch pad to open a popup picker dialog box and search for entities. The editor class derives from Microsoft.SharePoint.WebControls.EntityEditorWithPicker.

 

 

 

 

Picker Dialog

The picker dialog is a popup window which appears when the SharePoint user wants to search for one or more entities. This dialog box can be opened by clicking the editor’s browse button. By default the picker dialog is setup to take a search expression and display the matches in the results panel.

The picker dialog class derives from Microsoft.SharePoint.WebControls.PickerDialog.

 

 

Query

The Query control provides the visual results component of the picker dialog. This is the class responsible for accepting the search criteria, obtaining a list of matching entries and creating the table of matching entries to be displayed inside the picker dialog. The query class derives from Microsoft.SharePoint.WebControls.PickerQueryControlBase.

Entity Model

 

Before any of the picker components can be developed we need to identify an entity object to represent the selected data. A simple city entity can be represented with the following model.

 

Bringing the Picker Controls to Life

 

Once an entity is defined the editor, picker dialog and query controls can be created. Each picker control has references to the other two controls which creates a dependency between each con trol. As a result creating the three controls before defining the control body simplifies the process. We begin by creating a class named CityEditor which derives from Microsoft.SharePoint.WebControls.EntityEditorWithPicker. Second, we create a class named CityPickerDialog which derives from Microsoft.SharePoint.WebControls.PickerDialog. Finally, we create a class named CityQueryControl which derives from Microsoft.SharePoint.WebControls.PickerQueryControlBase. The three city picker controls have the following properties and methods.

 

 

 

Editor

The editor provides an entry point for the user to express the selected entities. The main job of the Editor is to validate entities provided by the user and provide a launching pad to open a picker dialog box to search for entities. We start by setting up the picker dialog by setting the PickerDialogType property to the type of our CityPickerDialog class. This informs SharePoint to use the CityPickerDialog control when searching for new cities.

 

We then want to define how entities are validated by our city picker. We do this by overriding the ValidateEntity method. I this method we inspect each city provided by the user. If the city is not already resolved we look for a matching city in the AllCities property of the CityManger class. If a valid city is found we mark the city resolved. If not city is found we return the city in the current unresolved state.

 

 

The remaining CityEditor methods are used to convert entities between a City and a PickerEntity and allow a programmer to set an initial list of selected cities.

Picker Dialog

The picker dialog control is the simplest picker class to create. It is used to setup the dialog window properties and the column properties used by the search results. We start by defining the results control used to display the matching cities.

 

 

Most of work is done in the constructor where we set the results controls column display names, column names and column widths.

 

Using the OnLoad method we setup the title and description of the dialog window.

 

Query

The query control is used to issue queries and return the results to the picker dialog. The CreateDataTable method is used to create a System.Data.DataTable from the columns defined by the picker dialog control. The GetEntity method is used to convert a DataRow to a PickerEntity when an item is selected. The interesting work performed by the query control occurs in the IssueQuery method.

 

The IssueQuery method takes the search parameters and obtains the search results. The CreateDataTable method is called to build a DataTable used to pass our data from the query control to the picker dialog. Once the DataTable is filled with the results of the search the results are passed to the picker dialog using the PickerDialog.Results property. Finally the number of matching records is returned to enable paging if necessary.

 

 

 

 

 

Putting the Picker to Work

 

Once the editor, picker dialog and query picker controls are in place we can add it to a SharePoint page in the same manner as any other control. The first order of business is to add a <SafeControl /> entry for our assembly to the web.config file and register the control namespace at the top of our .ASPX page. We can then add the editor control.

 

City Editor (Single Entry)

City Editor (Multiple Entries)

 

 

The final step is to obtain a list of resolved entities when a page action occurs. To get a list of resolved entities simply call the ResolvedEntities property of the CityEditor instance.

Conclusion

 

Many people see SharePoint as an extremely effective collaborative solution. As a software developer you should also notice the folks at Microsoft have done an excellent job making SharePoint a platform for your custom applications. By taking a bit of time to understand the SharePoint architecture you can take full advantage of the infrastructure provided. Custom pickers are an effective way to maintain consistency with the SharePoint UI while reducing the amount of work required creating a custom solution.

Visual Studio solution for picker sample

Related Posts

080912_0319_HowtoAddthe1.png 080912_0319_HowtoAddthe2.png 080912_0319_HowtoAddthe3.png 080912_0319_HowtoAddthe4.png 080912_0319_HowtoAddthe5.png 080912_0319_HowtoAddthe6.png 080912_0319_HowtoAddthe7.png 080912_0319_HowtoAddthe8.png 080912_0319_HowtoAddthe9.png 080912_0319_HowtoAddthe10.png 080912_0319_HowtoAddthe11.png 080912_0319_HowtoAddthe12.png

How to Add the Meeting Workspace Button in the Outlook 2010 Ribbon to Create a Meeting Workspace

image.png image_thumb.png SharePointDropDownFilter.png

SharePoint 2010 Tutorial Video: Drop-Down Filters

Loading SharePoint Dlls into Reflector

cmdSysprep.png cmdSysprep_thumb.png startCMDAdmin.png startCMDAdmin_thumb.png cmdBCDEditEnum.png cmdBCDEditEnum_thumb.png cmdBCDEditCopy.png cmdBCDEditCopy_thumb.png cmdMark.png cmdMark_thumb.png cmdHighlight.png cmdHighlight_thumb.png cmdPaste.png cmdPaste_thumb.png cmdBCDEditDevice.png cmdBCDEditDevice_thumb.png cmdBCDEditDetectHAL.png cmdBCDEditDetectHAL_thumb.png

SharePoint 2010 Lab Environment Part 2 – Bootable vhd Files

8 Comments

  1. Avatar of ARFI

    ARFI - June 7, 2011, 1:24 pm

    Hi Jeremy,

    I’m trying to do something similar to this and my requirement also includes pagination in the Webpage Dialog part (this because the picker is using a database to retrieve the results, instead of going to AD). Any idea on how to do this?

    Thanks.

  2. Avatar of Jeremy Luerkens

    Jeremy Luerkens - June 7, 2011, 2:45 pm

    I don’t believe the SharePoint dialog picker provides support for pagination. The idea is to provide additional search criteria to narrow your search results to help locate the target item. When more control over the dialog window is required you will have to build your own dialog page. The ‘window.showModalDialog’ method is a great tool to display your own custom dialog box and provide results back to the calling page.

  3. Avatar of Anthony Nguyen

    Anthony Nguyen - June 8, 2011, 4:13 am

    thanks for your great post!

    I have a concern regarding to the item editing issue. Assume CITY items are stored in a SharePoint list, this custom picker will pick CITY from this list. Soon after I edit/add/delete a new CITY into the list, how can the Picker Dialog update these changes in the search result ? I think Event Handler is a suitable approach, but I don’t know what modules to update.

    Thanks a lots!

  4. Avatar of Jeremy Luerkens

    Jeremy Luerkens - June 8, 2011, 8:41 am

    Each time a user opens the dialog box and enters new search criteria the IssueQuery method of the CityQueryControl class is called. This method can query the latest set of list items in the City list by issuing a CAML query containing the search criteria. The matching cities from of the query will be displayed in the Results control. How the Results control is populated is entirely up to the developer. You are free to replace the CityManager.AllCities property call with a call a Database, Activie Directory or any system containing the desired picker data.

  5. Avatar of Ernesto Pavel Rosales Camacho

    Ernesto Pavel Rosales Camacho - August 25, 2011, 11:27 am

    Hi, great post!, I’ve finished my custom picker, it works fine, I’m retrieving results from a store procedure form a data base. But I don’t know how to show in the picker dialog all the data before the user writes something, then the search box will fuction as a filter.

    Any idea ?

    Regards!

  6. Avatar of Jeremy Luerkens

    Jeremy Luerkens - November 8, 2011, 10:43 am

    To populate the dialog when it is first loaded you need to set the ‘DataTable : Results’ property in the ‘CityPickerDialog.OnLoad’ method with the desired data. The code will be very similar to the ‘CityQueryControl.IssueQuery’ method, as shown above, without the search filter.

  7. Custom Picker in Sharepoint « Sharepoint… - December 5, 2011, 12:41 pm

    [...] there is more we can do with pickers in Sharepoin. We can define our own pickers. Jeremy Luerkens gives one such example and a code sample (!). Another example can be found in Sharepoint as a Development Platform (p. 661), even though it [...]

  8. how to build a custom picker control | web technical support - April 7, 2012, 4:31 am

    [...] till now the only blog that talks about building a custom picker is : http://sharepointsolutions.com/sharepoint-help/blog/index.php/2009/10/create-a-custom-picker-in-shar… [...]

Leave a Reply