People Picker Extensions - Nintex Forms

Document created by emily.billing@nintex.com Champion on Jul 9, 2014Last modified by emily.billing@nintex.com Champion on Jul 16, 2014
Version 5Show Document
  • View in full screen mode

With the latest release of Nintex Forms 2010 v1.5.2 and Nintex Forms 2013 v2.3.2 released on 5th June 2014, we’ve provided a client side API to programmatically work with the new people picker control that was introduced in the last version of Nintex Forms.

 

Customers who have JavaScript which works with the old people picker control, (<v.1.3 for 2010 or <v.2.2 for 2013) will need to update their code so it is compatible with the new people picker control API.

 

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

 

Name

Description

Parameters

added( func )

Executes the specified function when an item is added to the people picker, 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  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 can either be the login name to remove or a predicate function.

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');

Search and add an item

The following code 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

  1. ins.search('domain\\jon.doe').done(function (data) {

ins.add(data[0]);

});

Remove a User

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

  1. 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.

Note: 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

  1. ins.remove('i:0#w|nintextest\\jon.doe');


The double backslash ‘\\’ 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: If there are multiple logins, 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, for example, to remove items without exactly matching the claims token.

Using a Predicate Function

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.PeoplePickerApi('#my_id');

 

//remove the users with the name ‘jon.doe’ in the login name from the people picker

  1. ins.remove(function() {

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

        return isMatch;

});

 

The People Control and using code

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:

  1. 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” });

});

2 people found this helpful

Attachments

    Outcomes