Tag Archives: people picker

Developing against the new people control in Nintex Forms

With the latest release of Nintex Forms (1.5 for 2010 and 2.3 for 2013), we’ve provided a client side API to programatically work with the new people picker control that was introduced in the last version of Nintex Forms.

Customers out there that have javascript that works with the old people picker control, (<1.3 for 2010 or <2.2 for 2013), will need to update their code to work with the new people picker control API.

The namespace of the helper API is NF.PeoplePickerApi and it provides the following functions:

Name Description Parameters
added( func ) Executes the specified function when an item is added to the people picker, either via code or UI. func – The function to execute
removed( func ) Executes the specified function when an item is removed from the people picker, either via code or UI. func – The function to execute
search( term ) Search for entities matching the search term. term – The search termResult – This returns a jQuery promise object. The done method will return an array of entity results in the following format:{value:”domain\\login”, label:”my label value”, type:”user”, email:”email@someone.com” }
add( value ) Add an item to the people picker control. value – the entity object in the following format:{value:”domain\\login”, label:”my label value”, type:”user”, email:”email@someone.com” }Note: A single search result can be directly specified
remove( valueOrPredicate ) Remove an item from the people picker control. value – the value to remove. This will be the login name to remove.
clear() Remove all items from the people picker control.

Usage Examples

To create an instance, use the new operator and specify the jQuery selector or the element.

var ins = new NF.PeoplePickerApi('#my_id');

The following snippet shows how to search and add an item to the people picker

var ins = new NF.PeoplePickerApi('#my_id');

//search for jon doe and add the first result to the people picker
ins.search('domain\\jon.doe').done(function (data) {
        ins.add(data[0]);
});

The following code snippet shows how to remove a user

var ins = new NF.PeoplePickerApi('#my_id');

//remove the user jon doe from the people picker
ins.remove('domain\\jon.doe');

The remove function takes a parameter “value” to remove a resolved entity. This value is the login value specified when the entity is created. Please note that if your environment has claims enabled, then the value should include the claims as well.

var ins = new NF.PeoplePickerApi('#my_id');

//remove the user jon doe from the people picker
ins.remove('i:0#w|nintextest\\jon.doe');

Note the the double ‘\\’ is only needed to escape a string in javascript. The login value can be obtained by calling the jQuery val() function on the element.

var ins = new NF.PeoplePickerApi('#my_id');

//get all the logins
var logins = $('#my_id').val();

Note that if there are multiple logins, then they will be separated by a semicolon (‘;’).  If the token was created using the data from the search method, then the “value” property of the search result will be the required login name.

This API can be extended to suit your needs, i.e. you can modify the “remove” method to, for example, remove items without exactly matching the claims token.

If you require more flexibility in choosing what to remove, you can pass in a predicate function. A predicate function simply returns “true” for the items to be removed. The following code snippet shows the use of a predicate function to remove any items that contain the word “jon.doe” in the login name. The “this” keyword holds the value of the current item.

var ins = new NF.PeoplePickerHelper('#my_id');

//remove the users with the name ‘jon.doe’ in the login name from the people picker
ins.remove(function() {

        var isMatch = this.indexOf('jon.doe') != -1;

        return isMatch;

});

Finally, when working with a people control, Nintex Forms must be initialized before your code is executed. To ensure Nintex Forms is initialized, wrap your code inside of a function literal and pass it to the NWF.FormFiller.Events.RegisterAfterReady() function, as seen below:

NWF.FormFiller.Events.RegisterAfterReady(function () {
    var ins = new NF.PeoplePickerApi('#my_id');
    ins.add({value:"domain\\login", label:"my label value", type:"user", email:"email@someone.com" });
});

Tom.

 

Advertisements