PeopleEditor Control

Introduction

The PeopleEditor control is a great control to easily select one or more users from the users known in the directory service of the server.

The control consists of 3 controls:

• a text box where you can fill out part or complete user name
• a button to check the filled out name(s)
• a Browse button to search for a user name

When you click the Browse button a dialog opens where you can search for specific user(s).

When you entered part of a name and click the Check Names button the entrance is checked agains the users in the directory service. When no exact match is found, the value is marked with a red line. Clicking on it will display a list with all matches from which you can select one.

 

Syntax

You can use this PeopleEditor control when developing application pages or control templates using the following syntax:

<spuc:PeopleEditor ID="PeopleEditor1" runat="server" width="350px"
                   AllowEmpty="true" MultiSelect="false" SelectionSet="User"  />

But only after you have added a directive at the top of the application page or control template:

<%@ Register TagPrefix="spuc" Namespace="Microsoft.SharePoint.WebControls"
             Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

If you are developing a web part you have to create the PeopleEditor control completely in code:

private PeopleEditor peopleEditor;
private void EnsureChildControls()
{
    peopleEditor = new PeopleEditor();
    peopleEditor.AutoPostBack = true;
    peopleEditor.ID = "PeopleEditor1";
    peopleEditor.AllowEmpty = false;
    peopleEditor.MultiSelect = false;
    Panel1.Controls.Add(peopleEditor);
}

This control is part of the Microsoft.SharePoint.dll and is located in the Microsoft.SharePoint.WebControls namespace.

 

Properties

There are also a number of properties/attributes you can set to configure the functionality of the PeopleEditor control:

•  AutoPostBack: if you want the control to react immediately when a user works with it, you have to set this property to true. Otherwise the control will react on page postback.
• AllowEmpty: Setting this to false obliges the user to fill out a user name. The default value is true. (Pay attention to this property: I was not able to make it work, and I’m not the only one).
• AllowTypeIn: Setting this property to false prevent users from filling out part of a name or complete name. In this case users can only use the Check Names button and Browse button to populate the control.
• CommaSeparatedAccounts: you can initialize the PeopleEditor control by entering a string of login names separated by a comma.
• EntitySeparator: the default is a ‘;’.
• ErrorMessage: you can change the default message by setting this property to a custom error message.
• ID: id of the control.
• MultiSelect: Setting this property to true allows users to select more than one user.
• NoMatchesText: you can change the default message that is displayed when no matches are found by setting this property to a custom error message.
• PlaceButtonsUnderEntityEditor: Setting this property to true displays the Check Names button and Browse button under the text box. The default is false.
• PrincipalSource: if you have more than one source from where users can be selected, you can set this property to the desired source.
• SelectionSet: this property accepts a comma-delimited string containing the different account types (defined in the AccountType enumeration) like User, DL, SecGroup, SPGroup

      objEditor.SelectionSet = "User,SecGroup,SPGroup";

• SharePointGroup: you can also limit the users that can be selected in the PeopleEditor control by setting this property to the name of a SharePoint group defined on the current web.
• ShowButtons: set this property to false if you don’t want to have the Check Names and Browse button displayed.
• ValidatorEnabled: if set to true, the entries in the text box are validated client-side.
• ValidateResolvedEntity: the default value is true to validate the resolved entity. You can set this property to false to prevent validation. 

The list above is not complete. You can find the complete list on MSDN. 

 

Methods

There are also a number of methods you can use:

• GetAccountFromSid: Retrieves the login name of an account associated with the security ID (Sid) that is passed into this method.
• UpdateEntities: you can use this method to f.e. initialize the PeopleEditor control.

      // populate the PeopleEditor with the current user
      System.Collections.ArrayList entityArrayList = new System.Collections.ArrayList();
      PickerEntity entity = new PickerEntity();
      entity.Key = SPContext.Current.Web.CurrentUser.LoginName;
      // this can be omitted if you're sure of what you are doing
      entity = PeopleEditor1.ValidateEntity(entity);
      entityArrayList.Add(entity);
      PeopleEditor1.UpdateEntities(entityArrayList);

• ValidateEntity: calling this method passing in an object instance of type PickerEntity ensures that the user exists in the directory service.

      entity = PeopleEditor1.ValidateEntity(entity);
 

Objects

When the CheckNames button is clicked a number of properties are populated by the internals of the control. You can inspect these properties:

• Accounts: this is an ArrayList of strings and contains the login names of all selected users 
• Entities: the contents of this property is unpredictable and I advise you not to use it. Use the ResolvedEntities property instead.
• ResolvedEntities: this is an ArrayList of PickerEntity objects (more details below)

The PickerEntity object contains following properties:

• Description: contains the login name of the user
• DisplayText: contains the display name of the user
• IsResolved: a boolean indicating whether the user was found in the directory service
• Key: contains the login name of the user
• EntityData: is an object with user data

The EntityData object consists of the following properties:

• DisplayName
• Email
• Department
• Title
• PrincipleType

The PickerDialog is a property of the the PeopleEditor control and represents the dialog that is displayed when the user clicks the Browse button.

 

Retrieving User Profile

One of my readers recently asked if it was possible to retrieve the user profile based on the selected user in the PeopleEditor control. Working with user profiles is only possible if you have a Shared Services Provider installed and the have the user profiles imported.

User Profile information can programmatically be accessed throught the UserProfileManager class. This class is located in the Microsoft.Office.Server.dll.

With the outcome of the PeopleEditor control you can show user profile details of the selected user. The Key property of the PickerEntity object contains the login name of the user. This value can be used to retrieve the user profile from the User Profile Manager.

        // retrieve profile information
        ServerContext ctx = ServerContext.GetContext("Litware SSP");
        UserProfileManager mgr = new UserProfileManager(ctx);
        try
        {
          PickerEntity selectedEntity = (PickerEntity)PeopleEditor1.ResolvedEntities[0];
          UserProfile profile = mgr.GetUserProfile(selectedEntity.Key);
          AddProfileRow("Title", profile["Title"].Value.ToString());
          AddProfileRow("Department", profile["Department"].Value.ToString());
          AddProfileRow("Email", profile["WorkEmail"].Value.ToString());
          if (profile.PersonalSite != null)
            AddProfileRow("Personal site", profile.PersonalSite.Url);
        }

Remark: The AddProfileRow method is a private method that adds a row and two cells to the UserProfileTable.

If you want to show all properties of the user profile, you can loop through the defined properties and retrieve them from the user profile:

        PickerEntity selectedEntity = (PickerEntity)PeopleEditor1.ResolvedEntities[0];
        UserProfile profile = mgr.GetUserProfile(selectedEntity.Key);
        //Get the properties
        PropertyCollection props = mgr.Properties;
        foreach (Property prop in props)
        {
          if (profile[prop.Name] != null && profile[prop.Name].Value != null)
             AddProfileRow(prop.Name, profile[prop.Name].Value.ToString());
          else
            AddProfileRow(prop.Name, string.Empty);
        }

 

But what if you want to use this control from within a web part?

When trying to use this control from within a web part (the classic web part for SharePoint 2007 or the Visual Web Part for SharePoint 2010), all of a sudden the PeopleEditor textbox is not visible anymore:

Unless you place it within a <div> element with a background color different from white:

<div style="background-color: Aqua">
    <spuc:PeopleEditor ID="PeopleEditor1" runat="server" Width="350px" AllowEmpty="true" MultiSelect="false" SelectionSet="User" />
</div>

resulting in

But propably this is not what you want. If you really really want a similar behavior as in a SharePoint application page with a border around the text box, you have to override some styles:

<style  type="text/css">    
    .ms-inputuserfield{ font-size:8pt; font-family:Verdana,sans-serif; border:1px solid #a5a5a5;}  
    div.ms-inputuserfield a{color:#000000;text-decoration: none;font-weight:normal;font-style:normal;}    
    div.ms-inputuserfield{padding-left:1px;padding-top:2px;}    
</style>  
<spuc:PeopleEditor ID="PeopleEditor1" runat="server" Width="350px" AllowEmpty="true" MultiSelect="false" SelectionSet="User" />

And this results in the desired layout: