All posts by Tom Shirley

About Tom Shirley

Software developer with 10 years experience in the industry. Working with the fantastic people at Nintex. Traditionally a Microsoft and SharePoint technologies .net developer who's moving increasingly into cross-platform web development.

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

Lookup function – Help page documentation

For anyone who’s using the Lookup function in Nintex Forms, here’s the in-product help page for reference:

Lookup function

The lookup function allows a form designer to retrieve data from a column within a SharePoint list and display that data on a form or use it in a formula.
A common requirement among form designers is the ability to surface SharePoint data from another list and optionally process that data. Displaying an entire list item or a list view is possible with the List Item and List View controls respectively, however these controls render html as their output which cannot be processed in a Nintex formula. In scenarios where you want to obtain a value from a list column, for display or processing in a formula, the lookup function is a viable approach.

Usage

Within a Nintex Form, the lookup function can be used within a:
  • Calculated Value control: Double click a calculated value control to access the Formula property.
  • Form Variable: Click on the Form Variables button in the ribbon menu to create a new Form Variable.
  • Rule: Click on the Rules button in the ribbon to create a new Rule.

How the lookup function obtains data

To understand how the lookup function determines what data to bring back, consider the following lookup function:
lookup(“listA”, “ID”, 1, “Title”)
This lookup will send a query to SharePoint, asking for list items within a list titled ‘listA’ and return the Title column value from any list items whose ID column value is 1.
Note: The match on the value is case-insensitive.
The lookup function does not support complex query construction; it determines what list items are included, as data to bring back, based on the filter column being an exact match to the value you specify. You can compose complex formulas with the formula builder if you need to build up a complex query, however be mindful that each lookup function will send an individual request to SharePoint for data.

Parameters

list title: The title of list that contains the data you are querying.
  • Required? Yes
  • Position: Must be first parameter in function.
  • Advanced usage: To point to a list in another site, precede the list title with the server relative url path of the site, then delimit the list title with a pipe ‘|’ symbol, e.g.  “/sites/siteCollection/siteA|customList”

column to filter on:
The name of the column in the list that you want to filter on. Specifically, this column will be used to filter which list items are treated as matches against the third parameter.
  • Required? Yes
  • Position: Must be second parameter in function.
value to filter on: The value you specify for this parameter is compared against each item in the list, if it matches the value for the column you specify in the second parameter, the list item data is returned.
  • Required? Yes
  • Position: Must be third parameter in function.
output column: The name of the column in the list that you want to get data from. Data from the output column is returned in the formula.
  • Required? Yes
  • Position: Must be fourth parameter in function.

multiple values <optional>:
Used to signify that you want multiple values returned from the lookup function. This should be used if there are more than one list item which matches the filter you’ve configured and you want an array of values to be returned.
  • Required? No
  • Position: Must be fifth parameter in function.
  • Usage: Specify the value ‘true’, without the quotes.
  • Note: The maximum items number of items that can be returned in a lookup function is limited to 1000.

value data type <optional>:
Use to manually set the underlying data type that SharePoint will compare your value as.
  • Required? No
  • Position: Must be sixth parameter in function.
  • Usage: The list of the most common SharePoint data types to query are: Text, Note, Number, Currency, Integer, Boolean, DataTime, Lookup, Choice, URL.

Additional Information

List location

The list you are querying­ can exist within the current site, or within sites within the current site collection.

Data In

The following types of data are supported for the ‘value to filter on’ parameter:
  • Text: Surround your text with a double or single quote.
  • Number: Does not need to be surrounded with quotes.
  • Date: Pass a date value from either a Date control, or use the date() runtime function to create a new date value.
  • Boolean: A true/false value. Does not need to be surrounded with quotes.
  • Lookup: A SharePoint lookup value of the format – 1;#text. Alternatively, the text value by itself, i.e. ‘text’.
  • User: A SharePoint person or group column type.
  • Managed Metadata: Specify the name of the term to match against.
Note: Null is a valid input value.
The lookup function does not currently support multiple values being passed in as the input value parameter. Only a single value is supported. I.e. you cannot pass an array of values into a lookup function.

Data Out

The returned column value will not be formatted by the lookup function unless it’s one of the following SharePoint types:
  • Lookup
  • User
For Example: Given a SharePoint Person column, the displayed value of a Person column in SharePoint may appear as “User A”, but the underlying SharePoint text is of the format “1;#UserA”.
If a lookup function is configured to return a Person column’s value, it will convert it into text, using the internal format of “1;#UserA”.
By default, the data returned from this function is for a single column in a list. You may want to return multiple column values: For example, where multiple list items matched a given query. To do this, append ‘true’, without the quotes, as the last parameter of the function. For multiple output values, they are returned inside an Array. An array is of the format [value1,value2].

Inserting an existing control, property or variable

You can use a Named Control, Item Property, Form Variable, Workflow Variable or a pre-defined property as the input value of a lookup function. All types of data to insert are listed in the Formula Builder dialog.
Note: Quotes are not necessary when inserting a control, property or variable.

Runtime behavior

The lookup function is dynamic; if any parameters that are passed into the function change during runtime, the lookup function re-fetches the data and triggers the formula to re-evaluate.
All lookup data is cached for 2 minutes to reduce network traffic.
All lookup functions are evaluated on load of a form, unless they are configured to not recalculate on view mode. This option is per control in the control property window.
Lookup functions are processed asynchronously, meaning they do not halt the form from operating while they fetch the SharePoint data and evaluate. This helps in scenarios where the network between you and the data is slow or physically far apart.
Lookup functions currently do not work in Nintex Mobile or Nintex Live Forms.

Dependent formulae

Formulae that depend on other formulae containing a lookup function will not wait before evaluating. Consider the following scenario of two Form Variables:
Variable A has the formula: Variable B + 1
Variable B has the formula: lookup(“listA”, “Title”, “Task1”, “ID”)
Variable A depends upon Variable B, however an individual formula only waits until all endogenous lookup functions are complete before evaluating. The result is that Variable A will momentarily evaluate to ‘1’, as Variable B has not yet completed. When Variable B does complete, it notifies Variable A to re-calculate, at which time Variable A displays the complete value of: ‘<Variable B’s lookup value> + 1’.
If you have multiple, dependent lookup formulae and require all lookup functions to be complete before displaying a result to the user, utilize a single formula with nested or chained lookup functions.

Security Considerations

The lookup function will perform the lookup of SharePoint data as the current user. Therefore, if the user filling out a Nintex Form does not have the necessary SharePoint access to the list or list item(s), the lookup function will not return any data.

Nested Functions

Lookup functions can be nested inside of other lookup functions. Lookup functions will evaluate inside out, (for example, a lookup function inside another lookup function will evaluate first) to maintain formula correctness.

Circular Reference

As a form designer, be mindful not to construct a formula which contains a circular reference. A circular reference is where a formula is dependent on another formula to complete, but that formula depends upon the original formula completing.
If a circular reference is accidentally configured, the lookup function will stop evaluating after a fixed number of cycles.

Troubleshooting

To help with troubleshooting issues, preview your Nintex Form and press F12 to open the IE developer toolbar. Next, click on the Script tab and ensure that the Console tab on the right is selected. Refresh your preview window by right clicking and selecting Refresh.  Logging will appear in the window, and help you to troubleshoot common misconfiguration/data access issues.

Lookup data from another list inside a Nintex Form

Background

A common requirement among form designers is the ability to surface SharePoint data from another list and optionally process that data. Displaying an entire list item or a list view is possible with the List Item and List View controls respectively, however the aforementioned controls render html as their output which cannot be processed in a Nintex formula. In scenarios where you want to obtain a value from a list column, for display or processing in a formula, the lookup function is a viable approach.

An example would be a purchase order form whose list of purchasable items is maintained in a central list within SharePoint.

Henceforth is an example of how to use the Lookup function.

A Purchase Order utilizing the Lookup function

Given a Products list containing the following purchasable items:

100113_2356_Lookupdataf1

We want to create a Nintex form allowing a user to purchase items from a centralized list. The first step is to create our Nintex Form with a Lookup control that is connected to the Products list.

part1

Let’s preview the form. We see that the control displays each item in the Products list as a selectable item in the dropdown:

100113_2356_Lookupdataf3

Next, users should be able to purchase multiple items; let’s put this control inside a repeating section and add a text box to capture the quantity of each item.

100113_2356_Lookupdataf4

Great – users can purchase different types of products and various quantities of each. Next, we want to show to the user the price of each item they select. To do so, we make use of the Lookup function.

The Lookup function

The lookup function allows a form designer to get data from a column within SharePoint.

As mentioned, we want to display the associated price of a given product depending on what the user selects to purchase. To do so, we drag on a calculated value control and configure it as follows:

lookup-function-for-price

100113_2356_Lookupdataf6

In the above screenshot you can see the filled out function. The first parameter tells the function to access a list called “Products”. We need to tell the function which item in the products list we are interested in, as we only want column data for one list item, not all of them.

The second and third parameters are for this purpose, it specifies which column to filter on (ID in this case) and the value in that column that should be matched against. You’ll notice that the third parameter is red and underlined. That is because it is a ‘named control’. I.e. the value comes from the lookup control we put on the form to allow users to select a product. This formula is now dynamic. When the ‘Product’ control’s value changes, this formula is re-run.

The last parameter is ‘Price’. This is the column name which we want to bring back and display.

Let’s hit preview and have a look:

basic-lookup-of-price

In the above animation you can see the behaviour of the lookup function as it fetches the price upon product selection in the dropdown.

The request to SharePoint happens asynchronously, so the form isn’t refreshed or held up while the data is being fetched.

This is the most basic scenario where we can see how powerful the lookup function is. We can now extend our form to show the total cost of products per item in our form, which is the formula Qty*Price, as well as a running total at the bottom of the repeating section:

100113_2356_Lookupdataf8

Incorporating Rules

What happens if a user is trying to order more than what’s in stock? Preferably we want to show that there is insufficient stock based on what’s in the Products list.

We can provide this ability by using the lookup function inside another calculated value control.

Add another Calculated Value control inside the repeater and open up the formula builder. For this control, we want to show the text ‘Insufficient Stock’ if the quantity in stock of a given product is less than the quantity entered by the user:

100113_2356_Lookupdataf9

We’ve named this control ‘InsufficientStock’. Now, this control will read ‘Insufficent Stock’ when the quantity entered is greater than what’s in stock.

Next, we will create a rule on the Quantity control to bold the text and display it in red only when the control reads ‘InsufficientStock’.
rule

Here is the final result with the rule to change the display format of the quantity control:

Lookup-function-final

Once you familiarize yourself with the lookup function, it opens up new possibilities with Nintex Forms. We value feedback so please post your experience using the Lookup function and what type of scenarios you’re using it in. Don’t forget to tell us about capabilities you’d like to see in future releases!

We’ve earmarked querying the user profile service as a next step for this feature, allowing a form designer to surface user profile data on a form 🙂

The Lookup function is available in version 2.2 for SP 2013, and version 1.4 for SP 2010.

Tom Shirley,
Senior Developer at Nintex.

A little custom styling can go a long way

A few weeks back, I helped my mate Dan Stoll in showing him how to make use of 3rd party Javascript libraries to implement tabbed pages within a Nintex Form. See this article to get up to speed: http://www.sharepointpub.com/jquery-ui-tabs-and-nintex-forms/

If you take a look at the end result in the linked article, it was functional, but it didn’t look very pretty. A quick look at some of the more popular websites on the net show some great examples (example one, two and three) of how a fairly standard web form can look.

Now, I’m not a web designer or formally trained in User Experience (UX), but I am a big fan of simple, bold, easy-on-the-eye forms.

With that in mind, I wanted to take the sample utilizing tabs one step further; I wanted to make it look as good as it should!

A Register form built with Nintex Forms

Here’s the form published to Nintex Live for anonymous access: http://ntx.lv/1ahndPs  <– Click the link to see what’s possible!

Have a play with the tabs and fill in some data. Don’t worry, you’re not actually signing up for anything 🙂

RegisterFormScreenshot1

Now, some people out there would think there’s no way this is a Nintex Form! Well, to them I’d say, think again. Our product is fairly extensible so that you can get what you need done by including a bit of CSS and JS…

The bottom line is the form is looking and feeling way more user friendly. It’s just a concept, so there are lots of room for improving things. But the takeaway is that custom styling can do a great deal in improving the usability of a Nintex Form.

So how do you go about getting something styled like this? Stay tuned for part 2 of this blog post which will be up shortly!

The obligatory ‘hello world’ blog post…

The catalyst for starting this blog is to share with the community some of the new features that we’re putting into Nintex Forms. I’m sure this blog will evolve over time, but the current objective is to get more information out into the public sphere on how to use Nintex Forms to its fullest potential.

If you’re not familiar with the name used for this site, ‘walking the stack’ is a programming term where a developer typically starts with a executing piece of code and ‘walks’ up the stack trace to investigate the path of execution, usually to troubleshoot something.

A quick intro on me.. I’m a developer based in Melbourne, Australia and currently working with the fantastic people at Nintex on their Nintex Forms product . My passions are computer programming and hiking around Australia. Hit me up on twitter @_TomShirley

Here’s a quick video sample of one of my hiking escapes for good measure!