cancel
Showing results for 
Search instead for 
Did you mean: 
Not applicable

People Picker Extensions - Nintex Forms

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

});

Labels: (1)
Reply
17 Replies
Not applicable

Re: People Picker Extensions - Nintex Forms

I want to use the "added" option of the PeoplePickerApi.

I have used the below code options

option:1

NWF$(document).ready(function(){

NWF.FormFiller.Events.RegisterAfterReady(function(){

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

ins.added(GetRequestorDetails);

});

});

this one fails on the "added" function. This fails in the NF.PeoplePickerHelper.js file with the message "Cannot read property 'options' of null"

option:2

NWF.FormFiller.Events.RegisterAfterReady(function(){

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

ins.added(GetRequestorDetails);

});

This returns 'NWF' is undefine.

Please explain how to use the added function.

0 Kudos
Accept as Solution Reply
Workflow Hero

Re: People Picker Extensions - Nintex Forms

Thanks Emily,

What options are there for programmers who are on version 2.2 - who presumably have the new People Picker control but don't have the new API?

0 Kudos
Accept as Solution Reply
Not applicable

Re: People Picker Extensions - Nintex Forms

Hi Pramod,

I had our dev team look into your question, and this is the response I received.

The code in option 1 is correct. However you are not accessing the control correctly in jQuery. From your code:

NWF$(document).ready(function(){

  1. NWF.FormFiller.Events.RegisterAfterReady(function(){

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

  1. ins.added(GetRequestorDetails);

});

});

He is trying to load a control with the id “varRequestor”. This is not correct as asp.net will auto generate a long ID for that control.

So to get this working, you will need to open the People picker control settings and under “Advanced” set “Store Client ID in JavaScript variable” to “Yes” and for “Client ID JavaScript variable name” specify “varRequestor” (without quotes ofc.). Then the code needs to be changed as:

….

var ins = new NF.PeoplePickerApi('#’ + varRequestor);

….

Please let us know if that helps!

Cheers

Emily

Accept as Solution Reply
Not applicable

Re: People Picker Extensions - Nintex Forms

Thanks Emily,

Was away for sometime.

It was string concatenation issue for the the control id.

This worked.

Accept as Solution Reply
Not applicable

Re: People Picker Extensions - Nintex Forms

Hi Martin,

I suppose you are looking for the querying user profile information and update few fields on the form depending the user in the people picker. I used Vadim's approach with some modification http://vadimtabakman.com/nintex-forms-querying-user-profiles.aspx

NWF$(function(){ var mysiterequest = NWF$.ajax({

url: "/_api/SP.UserProfiles.PeopleManager/GetMyProperties",

method: "GET",

headers: {

"accept": "application/json; odata=verbose"

}

});

mysiterequest.then(

function(data){

NWF$('#' + varDisplayName).val(data.d.DisplayName);

NWF$('#' + varPosition).val(GetUserProperty(data,"SPS-JobTitle"));

NWF$('#' + varEmail).val(data.d.Email);

});

function GetUserProperty(data,propertyName){

var objects = data.d.UserProfileProperties.results.filter(function (e1) { return e1.Key == propertyName;});

if (objects.length > 0){

return objects[0].Value;

}

else{

return '';

}

}

});

I am extracting the Display Name, Email and Job Title of the current logged in user.

To get the list of properties and values, enter

<SharePoint Portal URL>/_api/SP.UserProfiles.PeopleManager/GetMyProperties

in the web browser and this will retrieve the user information. Copy it to Visual Studio and the structured xml is readable.

Get the Key and pass it to propertyName parameter.

This script can either be added directly to the form settings or include the javascript location.

I have started using this extensively

Hope this helps

0 Kudos
Accept as Solution Reply
Workflow Hero

Re: People Picker Extensions - Nintex Forms

Please update this page.  When getting the logins, the following code did not work for me:

var logins = $(‘#my_id’).val();

It should be:

var logins = NWF$(‘#my_id’).val();

Took me awhile to find it.

0 Kudos
Accept as Solution Reply
Workflow Hero

Re: People Picker Extensions - Nintex Forms

When will this be available in Nintex Forms for Office 365?

Accept as Solution Reply
Not applicable

Re: People Picker Extensions - Nintex Forms

Emily,

Great post. However, please fix the original post to fix the get control. It should be like below.

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

Thanks

0 Kudos
Accept as Solution Reply
Not applicable

Re: People Picker Extensions - Nintex Forms

Hello,

does this api work on O365? if so, Do I need to reference a script to make it work?

thanks

0 Kudos
Accept as Solution Reply