SharePoint 2013: Client Side People Picker

Introduction

SharePoint 2013 introduced client side people picker which can also be used from SharePoint apps. As like other SharePoint controls, the new people picker control is not well documented. I’ve reversed engineered the client side people picker control and tried to put some light in this dark area.

 

Functions

In the code snippet below, you can use user login id, email address as the key resolve the user in people picker.

Add Unresolved User

If you have user login Id or email address you can use them as key to add the user in people picker as shown below. By passing the ‘true’ as the last parameter in AddUnresolvedUser means, people picker will use the key to query the user details from server.

var peoplePicker = this.SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan;
var usrObj = { 'Key': loginIdOrEmail };
peoplePicker.AddUnresolvedUser(usrObj,true); 

 

Add users or show auto suggest

If you would like to show auto suggest box using javascript, you can use the following code snippet. if you pass true in the second parameter for AddUserKeys function, people picker will show the auto-suggest box, otherwise it’ll try to resolve the user. In case of passing true, you can pass any search-text and people picker will show the autosuggest based on the input search text.

var peoplePicker = this.SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan;
peoplePicker.AddUserKeys(loginIdOrEmailOrSearchText, false); //true shows the auto-suggest box, false resolve the user

 

Show Error Message

You can show an error message using code snippet as shown below:

SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan.ShowErrorMessage('Error message...')

As as result you will the following error message:

 

IsEmpty

You can check if People picker is empty using the following code snippet. For your information, if there’s any text in the people picker textbox IsEmpty will return false. Basically it’ll check if there’s any resolved or unresolved text in the people picker editor textbox.

SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan.IsEmpty()

 

HasResovledUsers

You can check if there’s any resolved user by using the following code snippet. If there’s at least one resolved user in the editor, it’ll return true (even if you have resolved or unresolved user, it’ll return true). The different between IsEmpty and HasResolvedUsers is that IsEmtpy will check if there’s any text in the people picker text box. Whereas HasResolvedUsers check if there’s any resolved users in the editor.

SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan.HasResolvedUsers()

 

Get Current Editor Value

If you can get the editor’s current unresolved value by using the following code snippet:

SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan.GetCurrentEditorValue()

The code snippet will not return any resolved value in the editor rather unresolved value

 

Enable/disable

You can use the following code snippet to enable or disable the people picker editor. However setting in disable state, prevent adding any new users in the editor but still user can remove existing resolved users by clicking cross (x) sign next to resolved user.

SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan.SetEnabledState(false)

I think the easiest way to disable completely is to hide the delete (cross X) icon. You can do so using the following script:

$('.sp-peoplepicker-delImage').hide()

 

Remove Resolved Users

There’s no direct support for removing resolved users using the people picker API. I’ve put the following snippet below which I think should work and removes a user by using selected user’s key.

var peoplePickerId = 'peoplePickerDiv';
var peoplePicker = this.SPClientPeoplePicker.SPClientPeoplePickerDict[peoplePickerId + '_TopSpan'];

//get selected users and select the second user (index 1) to remove
var selectedUsers = peoplePicker.GetAllUserInfo();
var userToRemoveKey = selectedUsers[1].Key; 

var resovledListElmId = peoplePicker.ResolvedListElementId;
var elementToRemove = '';
$('#' + resovledListElmId).children().each(function(index, element) {
    if (element.id.startsWith(peoplePickerId + '_TopSpan_' + userToRemoveKey + '_ProcessedUser')) {
        elementToRemove = element;
        return false;
    }
});

peoplePicker.DeleteProcessedUser(elementToRemove);

Simply, for all resolved users people picker creates span elements with id in the form ‘{peoplepickerid}_TopSpan_{userKey}_ProcessedUser_{index}’. So if we know the user key we want to remove, we can find the corresponding resolved user’s span element. Then finally people picker’s ‘DeleteProcessedUser’ method is used to remove the selected user.

 

Events

There’s few events available in the people picker control as described below. All of these events will get two parameters – first one is the people picker id and second parameter is an array of selected users.

On Control Value Changed

This event will be fired if anything changes, like if user type text, user select a user from auto-fill list or user removes selected user. You can easily hook into the event as shown below:

    this.SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan.OnValueChangedClientScript=function (peoplePickerId, selectedUsersInfo) {
        console.log('inside OnValueChangedClientScript');
    };

 

On Control Resolved Users Changed

This event will be fired as soon as an user is resolved ( i.e., a resolved user is selected). You can hook into the event as shown below:

    this.SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan.OnUserResolvedClientScript = function (peoplePickerId, selectedUsersInfo) {
        console.log('inside OnUserResolvedClientScript');
    };

 

On Control Validate

The people picker control validate it’s values – sometimes when values are changed or you can fire the event by yourself by calling the method ‘Validate’. You can hook into the event as shown below:

    this.SPClientPeoplePicker.SPClientPeoplePickerDict.peoplePickerDiv_TopSpan.OnControlValidateClientScript = function (peoplePickerId, selectedUsersInfo) {
        console.log('inside OnControlValidateClientScript');
    };

 

Conclusion

I’ve tried to explain the API but you all are welcome to provide any feedback or suggestions or enhancements in this unofficial documentation.