PeopleQueryControl Class

Description

The Microsoft.SharePoint.WebControls.PeopleQueryControl class inherits from the Microsoft.SharePoint.WebControls.SimpleQueryControl class which provides the data retrieval query services for Microsoft.SharePoint.WebControls.PickerDialog objects. Use of PeopleQueryControl as the data service layer provides a PickerDialog object with data searching and display targeted to people, exposed through the Microsoft.SharePoint.WebControls.PeoplePickerDialog class.

PeopleQueryControl work is performed by overriding the inherited SimpleQueryControl.IssueQuery method which is the major data retrieval method. In order to set the returned data value(s) to the PickerDialog class, it is sets the PickerDialog.Results property which must be of System.Data.DataTable type. As well, the SimpleQueryControl.GetEntity method is overridden which accepts a System.Data.DataRow type as a parameter, representing a particular DataRow out of the previously built DataTable. This is used in order to strongly type a Microsoft.SharePoint.WebControls.PickerEntity object in order to ensure entity data integrity.

In order to support the search into people, two methods out of the SPUtility class are used: SPUtility.SearchPrincipals and SPUtility.SearchWindowsPrincipals depending on the URL zone that the query is being executed in.

Usage Scenario

The primary usage of PeopleQueryControl within shipped software is represented when searching for people through a shipped, customary SharePoint environment in what is known as the "People Picker", found in field types, and other miscellaneous locations. PeopleQueryControl provides the data context for the picker to function. However, it is possible to use the control in the same fashion as any SimpleQueryControl when building custom EntityEditors. It should be noted that the class is sealed, so it is not possible to inherit from the class.

In the below example, the MyPickerDialog class is inheriting from the PickerDialog class. MyPickerDialog contains a parameterless constructor, however is calling the base constructor passing in a custom MyEntityEditor object which inherits from the EntityEditorWithPicker class and a PeopleQueryControl object which inherits from the SimpleQueryControl class. Following, in the MyPickerDialog constructor, we are building the relevant ArrayList objects for the custom PickerDialog to use by casting with the TableResultControl type against the PickerDialog.ResultControl, allowing the required values to be exposed via their properties.

C# Code Example

public class MyPickerDialog : PickerDialog
{
public MyPickerDialog() : base(new PeopleQueryControl(), new TableResultControl(), new MyEntityEditor())
{
ArrayList columnDisplayNames = ((TableResultControl)base.ResultControl).ColumnDisplayNames;
columnDisplayNames.Clear();
columnDisplayNames.Add("Name");
ArrayList columnNames = ((TableResultControl)base.ResultControl).ColumnNames;
columnNames.Clear();
columnNames.Add("Name");
ArrayList columnWidths = ((TableResultControl)base.ResultControl).ColumnWidths;
columnWidths.Clear();
columnWidths.Add("100%");
}
}

VB.NET Code Example

Public Class MyPickerDialog
Inherits PickerDialog
Public Sub New()
MyBase.New(New PeopleQueryControl(), New TableResultControl(), New MyEntityEditor())
Dim columnDisplayNames As ArrayList = DirectCast(MyBase.ResultControl, TableResultControl).ColumnDisplayNames
columnDisplayNames.Clear()
columnDisplayNames.Add("Name")
Dim columnNames As ArrayList = DirectCast(MyBase.ResultControl, TableResultControl).ColumnNames
columnNames.Clear()
columnNames.Add("Name")
Dim columnWidths As ArrayList = DirectCast(MyBase.ResultControl, TableResultControl).ColumnWidths
columnWidths.Clear()
columnWidths.Add("100%")
End Sub
End Class

Adam Buenz
SharePoint Foundation MVP - http://www.sharepointsecurity.com