Here at Summit 7 Systems, we are not just a Nintex Partner – we are Nintex customers. With such a powerful suite of tools at our finger tips, we're constantly on the prowl for ways to innovate and stretch our development capabilities on the platform.
Nintex is known for how quickly and easily it can automate an organization's business processes, but did you know that it can crown champions?
In case you missed our Conquer Your Bracket contest this spring during March Madness©, we challenged ourselves to push the limits of Nintex and do just that!
One of the key technical hurdles encountered with such a contest was the creation of dynamic drop-down controls, the form needed to allow users to make choices based on what they've previously chosen while also steering them away from invalid selections.
This blog seeks to demonstrate how jQuery can be leveraged within a Nintex Form to bring cascading drop-down functionality to Choice Controls.
For this walkthrough, we'll be building a small four-man tournament (see below). Let's get to it!
Are you more of a kinesthetic learner? Included at the bottom of the blog is a download link so you can follow along with a sample on premise form.
Laying the Foundation
To get started, we need to setup the infrastructure for capturing our Nintex form's data.
a. Create a custom SharePoint list – I called mine "CASCADING DROP-DOWNS ASSET."
i. Using the ribbon in the top bar, navigate to List Settings.
ii. Next, add the following single-line textbox columns to your custom list:
Building the Form
Now that we've got our storage model in place, we'll setup the necessary form controls within Nintex's form designer to support our four-man tournament. To start, we need to create Label Controls for each contestant.
a. Using the Form Controls pane, drag-and-drop a label control for each of the contestants into your form. In our case, we've got four contestants, so we'll need four label controls.
b. For each contestant, right-click the label control and add a unique CSS class (i.e. Contestant_01) in the Settings menu.
c. Click Save.
Now that we've got labels in place for each contestant, we need to create Choice Controls (drop-downs) so that our users can predict the winners of each match-up in our contest.
a. Using the Form Controls pane, drag-and-drop a choice control for each cascading dropdown (contestant match-up) needed.
b. For each choice control added, navigate to Settings and configure the following:
i. Ensure the Display format is set to Drop down list.
ii. Ensure that "Fill-in" choices are not allowed.
iii. Within the Control CSS class property, supply a unique class for the dropdown (i.e. SF_Selection_01_DropDown customDropDown) as well as a shared dropdown class (i.e. customDropDown).
iv. Set the Use custom "Please select" text property to Yes.
v.Set the Custom "Please select" text property value to "…".
Adding the Code
Now that our form controls are in place, let's turn our attention to the jQuery required to bring our choice controls to life. Here's what we need:
Our first function, setInitialChoiceControl, assigns option values to our "SEMIFINALS" choice controls. The option values for these choice controls are retrieved from our static contestant labels.
Building on our first function dealing with static labels, the setDynamicChoiceControl function allows us to react to changes made to a pair of parent choice controls (drop-downs) and update a subsequent choice controls with those previously selected options – thus cascading.
Let's incorporate the above code into our Nintex form. To do this:
d. Click Save.
We're close! With the above logic in place, you should now be able to demo your form and see the cascading choice controls behaving as expected. However, we still need to store this data to our SharePoint list.
In our form's current state, if you were to connect each choice controls to a SharePoint list column and attempt to submit your form, you'd encounter a big ugly invalid view-state error!
This error occurs because options appended to a .NET list control dynamically from the client will not be reflected in the code behind (server side).
In order to resolve this issue and configure our form for error-free submission, we need to first create underlying Single Line Textbox Controls for each of our choice controls:
a. Using the Form Controls pane, drag-and-drop a single line textbox control alongside each of your choice controls (contestant match-ups).
b. For each textbox control added, navigate to Settings and configure the following:
i. Set the Connected to property to the SharePoint List column for that given match-up (i.e. SF_Selection_02).
ii. Set the CSS Class property to a value of "invisible". We'll use this class in our form's CSS to better hide these textboxes.
(different ID than your choice control however).
c. Once more, right-click your textbox controls and Send to Back.
i. Now slide each textbox behind each match-up's choice control.
Populate the underlying text-box controls with the values selected in our choice controls.
- These text-boxes are what we've associated with our SharePoint list columns for data storage.
Disable all of our choice controls so that the view-state is no longer invalidated when the form is submitted.
Finally, we need to:
i. Right-click your Save button and go into Settings.
iii. Click Save.
There you have it – our form is now complete!