SharePoint Client People Picker Control Helper


The SharePoint people picker client-side control is a bit of an opaque beast, many times when you’re doing a client-side customisation you might want to Add or Remove person or group entities or otherwise examine the list of entities the user has selected.

peoplepicker00

The good news is that there is an API of sorts found in clientpeoplepicker.js, as long as you can target the specific people picker control you’re interested in.

The samples that follow are written in TypeScript but are easily converted to JavaScript, see the GIST at the end of the post for the complete module.

Get a People Picker Control Instance.

	public static getControl(internalColumnName) : SPClientPeoplePicker {
		if (!internalColumnName || !internalColumnName.length) {
			return null;
		}
		
		var ppTopLevelDiv:JQuery = $(".sp-peoplepicker-topLevel[id^='" + internalColumnName + "_']");
		if (!ppTopLevelDiv.length) return null;
		var control = SPClientPeoplePicker.SPClientPeoplePickerDict[ppTopLevelDiv[0].id];
		return control;
	}

This yields the SharePoint people picker control for the (Internal) column name specified.

Clear all Entities from a People Picker Control.

	public clear(): void {
		if (!this._control || !this._control.ResolvedListElementId) return;

		$(document.getElementById(this._control.ResolvedListElementId))
			.children()
			.each( (i:number, el:HTMLElement ) => {
				this._control.DeleteProcessedUser(el);
			});
	}

Remove an Entity from a People Picker Control.

	public removeEntity(entityKey : string): boolean {
		if ( 	(!entityKey || !entityKey.length) ||
				(!this._control || !this._control.ResolvedListElementId) )return;
		var removed: boolean = false;
		$(document.getElementById(this._control.ResolvedListElementId))
			.children()
			.each( (i:number, el:HTMLElement ) => {
				if ((el.id.indexOf('membership|'+entityKey+'_') !== -1) ||
						(el.id.indexOf('_'+entityKey+'_') !== -1) ) {
					this._control.DeleteProcessedUser(el);
					removed = true;
				}
			});
		return removed;
	}

Add a Resolved Entity to a People Picker Control.

	public addResolvedEntity(entityKey: string, search?: boolean): void {
		if ( 	(!entityKey || !entityKey.length) ||
				(!this._control || !this._control.ResolvedListElementId) )return;
		this._control.AddUserKeys(entityKey, search);
	}

The supplied entityKey is either a user email address (Office365) or user account name (On-Premises) or a SharePoint Group name

Add an Unresolved Entity to a People Picker Control.

	public addUnresolvedEntity(entityText: string): void {
		if ( 	(!entityText || !entityText.length) ||
				(!this._control || !this._control.ResolvedListElementId) )return;
		var ppUserInput = $(document.getElementById(this._control.EditorElementId));
		ppUserInput.val(entityText);
		this._control.AddUnresolvedUserFromEditor(true);
	}

This is equivalent to the user typing into the edit box

Return all Entity Info from the People Picker Control.

	public getEntities(): ISPClientPeoplePickerEntity[] {
		var userInfo = this._control.GetAllUserInfo();
		return userInfo || ([] as ISPClientPeoplePickerEntity[]);
	}

GIST

"use strict";
/**
* To debug in browser console;
*
* require(['lib/sppeoplepickerhelper'], function(sppeoplepickerhelper) { window.PeoplePickerHelper = sppeoplepickerhelper; } );
* var sme = new PeoplePickerHelper('SME');
*
*/
/**
* PeoplePickerHelper
*/
class PeoplePickerHelper {
private _internalColumnName:string;
private _control:SPClientPeoplePicker;
/** constructor
* @param {any} internalColumnName
*/
constructor(internalColumnName) {
this._internalColumnName = internalColumnName;
this._control = PeoplePickerHelper.getControl(this._internalColumnName);
}
/** retrieves the people picker control
* @returns any
*/
public static getControl(internalColumnName) : SPClientPeoplePicker {
if (!internalColumnName || !internalColumnName.length) {
return null;
}
var ppTopLevelDiv:JQuery = $(".sp-peoplepicker-topLevel[id^='" + internalColumnName + "_']");
if (!ppTopLevelDiv.length) return null;
var control = SPClientPeoplePicker.SPClientPeoplePickerDict[ppTopLevelDiv[0].id];
return control;
}
/**
* removes all entities from the people picker control
*/
public clear(): void {
if (!this._control || !this._control.ResolvedListElementId) return;
$(document.getElementById(this._control.ResolvedListElementId))
.children()
.each( (i:number, el:HTMLElement ) => {
this._control.DeleteProcessedUser(el);
});
}
/**
* removes an entity from the people picker control
* @param {string} entityKey - user email address or SP group name
* @returns boolean - true if an entity was removed
*/
public removeEntity(entityKey : string): boolean {
if ( (!entityKey || !entityKey.length) ||
(!this._control || !this._control.ResolvedListElementId) )return;
var removed: boolean = false;
$(document.getElementById(this._control.ResolvedListElementId))
.children()
.each( (i:number, el:HTMLElement ) => {
if ((el.id.indexOf('membership|'+entityKey+'_') !== -1) ||
(el.id.indexOf('_'+entityKey+'_') !== -1) ) {
this._control.DeleteProcessedUser(el);
removed = true;
}
});
return removed;
}
/**
* adds an unresolved entity to the people picker control
* @param {string} entityText
*/
public addUnresolvedEntity(entityText: string): void {
if ( (!entityText || !entityText.length) ||
(!this._control || !this._control.ResolvedListElementId) )return;
var ppUserInput = $(document.getElementById(this._control.EditorElementId));
ppUserInput.val(entityText);
this._control.AddUnresolvedUserFromEditor(true);
}
/**
* adds a resolved entity to the people picker control
* @param {string} entityKey - user email address or SP group name
* @param {boolean} search?
*/
public addResolvedEntity(entityKey: string, search?: boolean): void {
if ( (!entityKey || !entityKey.length) ||
(!this._control || !this._control.ResolvedListElementId) )return;
this._control.AddUserKeys(entityKey, search);
}
/**
* returns all resolved user information
* @returns ISPClientPeoplePickerEntity[]
*/
public getEntities(): ISPClientPeoplePickerEntity[] {
var userInfo = this._control.GetAllUserInfo();
return userInfo || ([] as ISPClientPeoplePickerEntity[]);
}
/**
* indicates if the supplied entity is selected in the people picker control
* @param {string} entityKey - user email address or SP group name
* @returns boolean
*/
public isEntitySelected(entityKey: string) : boolean {
if (!entityKey || !entityKey.length) return false;
var r:RegExp = new RegExp('^'+entityKey+'$', "gi");
var isMatched: boolean = false;
var entities: ISPClientPeoplePickerEntity[] = this.getEntities();
$.each(entities, (index:number, entity:any) => {
if (entity.EntityData) {
if (entity.EntityData.Email && entity.EntityData.Email.match(r)) {
/** matched a user */
isMatched = true;
return false; /** break the loop */
} else if (entity.EntityData.SPGroupID && entity.EntityData.AccountName && entity.EntityData.AccountName.match(r)) {
/** matched a SP Group */
isMatched = true;
return false; /** break the loop */
}
}
});
return isMatched;
}
}
/** for ES6 use
export default PeoplePickerHelper;
*/
/** for ES5 compatible use with RequireJS */
export = PeoplePickerHelper;

Published by

Phil Harding

SharePoint Consultant, Developer, Father, Husband and Climber.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.