Using client side people picker with javascript

Question

I found this this documentation on how to use the client side people picker and have it working on my page. Basically you load a bunch of js files, setup a schema, and then initialize the picker.

I'm trying to find any documentation of how you set up the schema and what kind of values you can use.

// Create a schema to store picker properties, and set the properties.
var schema = {};
schema['PrincipalAccountType'] = 'User,DL,SecGroup,SPGroup';
schema['SearchPrincipalSource'] = 15;
schema['ResolvePrincipalSource'] = 15;
schema['AllowMultipleValues'] = true;
schema['MaximumEntitySuggestions'] = 50;
schema['Width'] = '280px';

// Render and initialize the picker. 
// Pass the ID of the DOM element that contains the picker, an array of initial
// PickerEntity objects to set the picker value, and a schema that defines
// picker properties.
this.SPClientPeoplePicker_InitStandaloneControlWrapper(peoplePickerElementId, null, schema);

For example I figured out that PrincipalAccountType values of User means users, SecGroup is some kind of security group, and SPGroup is SharePoint groups. I couldn't figure out what DL is for. What exactly do those mean and are those the only choices?

I also can't figure out what properties I can use in the schema. Are those the only ones?

This documentation seems to list the properties for the people picker, but they don't quite match up. For example, in the code sample I found there is a schema['AllowMultipleValues'] but in the property list there is AllowMultipleEntries.

From the list of properties I've tried some like Tooltip which didn't work, but Title did set the tooltip.

Does anyone have a good source of information on how to actually work with and configure a client side people picker when using javascript on the page?

Edit Bonus question

In the init function what is the second argument? Must it always be null?

SPClientPeoplePicker_InitStandaloneControlWrapper(pickerElementId,null,schema)

Answer 1

What are the PrincipalAccountType values

• User = single user
• DL = AD distribution list
• SecGroup = AD security group
• SPGroup = SharePoint group

Reference

All Properties

You can check the constructor for all possible properties (and some more stuff but you should be able to distinguish them).

The consturctor is located in /_layouts/15/clientpeoplepicker.js:

function SPClientPeoplePicker(controlProps) {
    this.TopLevelElementId = controlProps.TopLevelElementId;
    this.EditorElementId = controlProps.EditorElementId;
    this.AutoFillElementId = controlProps.AutoFillElementId;
    this.ResolvedListElementId = controlProps.ResolvedListElementId;
    this.InitialHelpTextElementId = controlProps.InitialHelpTextElementId;
    this.WaitImageId = controlProps.WaitImageId;
    this.HiddenInputId = controlProps.HiddenInputId;
    if (typeof controlProps.Required != "undefined")
        this.AllowEmpty = !Boolean(controlProps.Required);
    if (typeof controlProps.ForceClaims != "undefined")
        this.ForceClaims = Boolean(controlProps.ForceClaims);
    if (typeof controlProps.AutoFillEnabled != "undefined")
        this.AutoFillEnabled = Boolean(controlProps.AutoFillEnabled);
    if (typeof controlProps.AllowMultipleValues != "undefined")
        this.AllowMultipleUsers = Boolean(controlProps.AllowMultipleValues);
    if (typeof controlProps.AllowEmailAddresses != "undefined")
        this.AllowEmailAddresses = Boolean(controlProps.AllowEmailAddresses);
    if (typeof controlProps.AllUrlZones != "undefined")
        this.AllUrlZones = Boolean(controlProps.AllUrlZones);
    if (typeof controlProps.VisibleSuggestions != "undefined")
        this.VisibleSuggestions = Number(controlProps.VisibleSuggestions);
    if (typeof controlProps.UseLocalSuggestionCache != "undefined")
        this.UseLocalSuggestionCache = Boolean(controlProps.UseLocalSuggestionCache);
    if (typeof controlProps.InitialSuggestions != "undefined" && controlProps.InitialSuggestions != null ) {
        this.InitialSuggestions = controlProps.InitialSuggestions;
        SPClientPeoplePicker.AugmentEntitySuggestions(this, this.InitialSuggestions, false)
    }
    if (typeof controlProps.UrlZone != "undefined")
        this.UrlZone = controlProps.UrlZone;
    if (typeof controlProps.WebApplicationID != "undefined")
        this.WebApplicationID = controlProps.WebApplicationID;
    if (typeof controlProps.SharePointGroupID != "undefined")
        this.SharePointGroupID = Number(controlProps.SharePointGroupID);
    if (typeof controlProps.PrincipalAccountType != "undefined")
        this.PrincipalAccountType = controlProps.PrincipalAccountType;
    if (typeof controlProps.EnabledClaimProviders != "undefined")
        this.EnabledClaimProviders = controlProps.EnabledClaimProviders;
    if (typeof controlProps.ResolvePrincipalSource != "undefined")
        this.ResolvePrincipalSource = controlProps.ResolvePrincipalSource;
    if (typeof controlProps.SearchPrincipalSource != "undefined")
        this.SearchPrincipalSource = controlProps.SearchPrincipalSource;
    if (typeof controlProps.MaximumEntitySuggestions != "undefined")
        this.MaximumEntitySuggestions = Number(controlProps.MaximumEntitySuggestions);
    this.PrincipalAccountTypeEnum = SPClientPeoplePicker.CreateSPPrincipalType(this.PrincipalAccountType);
    var fnUserCallback = controlProps.OnValueChangedClientScript;
    this.OnValueChangedClientScript = fnUserCallback != null ? eval(fnUserCallback) : null ;
    var fnResolvedCallback = controlProps.OnUserResolvedClientScript;
    this.OnUserResolvedClientScript = fnResolvedCallback != null ? eval(fnResolvedCallback) : null ;
    var fnControlValidateCallback = controlProps.OnControlValidateClientScript;
    this.OnControlValidateClientScript = fnControlValidateCallback != null ? eval(fnControlValidateCallback) : null ;
    this.AutoFillControl = null ;
    this.TotalUserCount = 0;
    this.UnresolvedUserCount = 0;
    this.UserQueryDict = {};
    this.ProcessedUserList = {};
    this.UnresolvedUserElmIdToReplace = "";
    if (typeof ClientCanHandleImn == "undefined" || !ClientCanHandleImn())
        SPClientPeoplePicker.ShowUserPresence = false;
    var topLevelElement = document.getElementById(this.TopLevelElementId);
    if (topLevelElement != null ) {
        topLevelElement.setAttribute("SPClientPeoplePicker", "true");
        if (Boolean(controlProps.Width))
            topLevelElement.style.width = controlProps.Width;
        if (controlProps.Width == "100%")
            topLevelElement.className += " ms-fullWidth";
        if (Boolean(controlProps.Rows) && Number(controlProps.Rows) != 0)
            topLevelElement.style.minHeight = String(Number(controlProps.Rows) * 16) + "px"
    }
    var editorElement = document.getElementById(this.EditorElementId);
    editorElement != null && editorElement.setAttribute("data-sp-peoplePickerEditor", "true");
    if (this.ShouldUsePPMRU())
        this.PPMRU = SPClientPeoplePickerMRU.GetSPClientPeoplePickerMRU();
    SPClientPeoplePicker.SPClientPeoplePickerDict[this.TopLevelElementId] = this
}

Bonus question

The second parameter is an array of users to prefill the peoplepicker. Here's a code example:

    var users = new Array(1);
    var defaultUser = new Object();
    defaultUser.AutoFillDisplayText = user.get_title();
    defaultUser.AutoFillKey = user.get_loginName();
    defaultUser.Description = user.get_email();
    defaultUser.DisplayText = user.get_title();
    defaultUser.EntityType = "User";
    defaultUser.IsResolved = true;
    defaultUser.Key = user.get_loginName();
    defaultUser.Resolved = true;
    users[0] = defaultUser;
    SPClientPeoplePicker_InitStandaloneControlWrapper('peoplePickerDiv', users, schema);

From http://blog.ianchivers.com/2013/05/client-side-people-picker-control-for.html