How to Create Cascading Choice Controls – Nintex Forms

Document created by Patrick Abel Champion on Jul 8, 2016Last modified by Patrick Abel Champion on Jul 9, 2016
Version 2Show Document
  • View in full screen mode

This asset seeks to demonstrate how JavaScript/jQuery can be leveraged within a Nintex Form to bring cascading drop-down functionality to Choice Controls.

s7_nintex_cascading_dropdowns_asset_demo (1).gif

This asset originated from a blog that can be located here : How to Create Cascading Choice Controls – Nintex Forms | Summit 7 Systems

 

Summit_7_logo_web_new.png

 

AuthorPatrick Abel
Long Description

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:

1. SF_Selection_01

2. SF_Selection_02

3. Finals_Selection

 

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

vi. Set the Store Client ID in JavaScript variable property to Yes.

vii. Within the Client ID JavaScript variable name property, supply a unique value for the dropdown (i.e. SF_Selection_01_DropDown)

NOTE: It’s critical that these are logically named as you’ll be using these CSS class and JavaScript client ID values in jQuery later to dynamically set subsequent (cascading) drop-downs.

 

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:

 

// Run once the page Document Object Model (DOM) is ready.
NWF$(document).ready(function () {
    DropDowns.setInitialChoiceControl('Contestant_01', 'Contestant_02', 'SF_Selection_01_DropDown');
    DropDowns.setInitialChoiceControl('Contestant_03', 'Contestant_04', 'SF_Selection_02_DropDown');
    DropDowns.setDynamicChoiceControl('SF_Selection_01_DropDown', 'SF_Selection_02_DropDown', 'Finals_Selection_DropDown');
});

var DropDowns = {
    // Populates choice control(s) for initial round drop-downs (label input)
    // @param {string} label1 : CSS class applied to first contestant label control. 
    // @param {string} label2 : CSS class applied to second contestant label control. 
    // @param {string} dropDown : CSS class associated with the choice control you wish to populate.
    setInitialChoiceControl: function (label1, label2, dropDown) {
        var x = NWF$('.' + label1).text();
        var y = NWF$('.' + label2).text();

        var selections = {
            val0: "...", // Needed for validation to force initial selection
            val1: x,
            val2: y
        };

        var currentDropDown = NWF$('.' + dropDown);
        currentDropDown.empty();

        NWF$.each(selections, function (val, text) {
            currentDropDown.append(NWF$('<option></option>').val(val).html(text));
        });
    },
    // Populates choice control(s) for cascading drop-downs
    // @param {string} dd1 : CSS class applied to first parent choice control. 
    // @param {string} dd2 : CSS class applied to second parent choice control. 
    // @param {string} dd3 : CSS class associated with the choice control you wish to dynamically populate based on changes in the above parent choice controls.
    setDynamicChoiceControl: function (dd1, dd2, dd3) {
        var choiceControl1 = NWF$('.' + dd1);
        var choiceControl2 = NWF$('.' + dd2);
        NWF$(choiceControl1).add(choiceControl2).change(function () {
            var x = NWF$('.' + dd1 + ' option:selected').text();
            var y = NWF$('.' + dd2 + ' option:selected').text();

            var selections = {
                val1: x,
                val2: y
            };

            var currentDropDown = NWF$('.' + dd3);
            currentDropDown.empty();
            currentDropDown.append(NWF$('<option></option>').val('val0').html('...'));

            NWF$.each(selections, function (val, text) {
                if (text != '...' && text != '') {
                    currentDropDown.append(NWF$('<option></option>').val(val).html(text));
                }
            });
        });
    }

}
}ASD}]

 

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:

a. Create a JavaScript (.js) file comprised of the above code snippet.

b. Upload this JavaScript to your SharePoint site – I chose the Site Assets document library.

c. Update your Nintex form to reference this external JavaScript file through Sittings > Advanced > Custom JavaScript Includes.

        d. Click Save.

 

Form Submission

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.

iii. Set the Store Client ID in JavaScript variable to Yes.

iv. Set the Client ID JavaScript variable name property to a unique value that corresponds to your match-up
(different ID than your choice control however).

v. Save.

c. Once more, right-click your textbox controls and Send to Back.

i. Now slide each textbox behind each match-up’s choice control.

Next, we need to employ some additional JavaScript when our form is submitted to work-around the invalid view-state issue. To do this, we need to:

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

 

var Buttons = {
  // This function is configured within Nintex Forms to trigger on click of Save/Submit
  onSave: function () {
  DropDowns.disableAll();
  DropDowns.populateTextBoxes();
  }
};

var DropDowns = {
  // Populates hidden single-line textbox with drop-down value (workaround for invalid view-state)
  populateTextBoxes: function () {
  DropDowns.populateTextBox(SF_Selection_01, SF_Selection_01_DropDown);
  DropDowns.populateTextBox(SF_Selection_02, SF_Selection_02_DropDown);
  DropDowns.populateTextBox(Finals_Selection, Finals_Selection_DropDown);
  },
  // Populates associated textbox with selected value from Choice Control (pt1 : workaround for invalid view-state)
  // @param {string} labelID : JavaScript Client ID variable for the hidden textbox. 
  // @param {string} dropdownID : JavaScript Client ID variable for the choice control associated with the hidden textbox. 
  populateTextBox: function (labelID, dropdownID) {
  var obj = NWF$('#' + labelID);
  obj.val(NWF$('#' + dropdownID + ' option:selected').text());
  },
  // Disables all choice controls (pt2 : workaround for invalid view-state)
  disableAll: function () {
  NWF$('.customDropDown').prop('disabled', true);
  }
}

 

Finally, we need to:

a. Integrate the above code into our external JavaScript file.

b. Update our submission button to execute this code when our Nintex form is submitted:

i. Right-click your Save button and go into Settings.

ii. Under the Advanced section, update the Client Click property with the following jQuery:

NWF$(document).ready(function(){Buttons.onSave();});

iii. Click Save.

There you have it – our form is now complete!

Dependencies

The creation of a custom SharePoint List (i.e. CASCADING DROP-DOWNS ASSET) with the following columns:

1. SF_Selection_01

2. SF_Selection_02

3. Finals_Selection

Support Info

Patrick Abel | Summit 7 Systems | patrick.abel@summit7systems.com

Compatibility

Nintex Forms 2013

Platform

SharePoint Server 2013

Screenshots

s7_nintex_cascading_dropdowns_asset_demo (1).gif

Additional Information

This asset originated from a blog that can be located here : How to Create Cascading Choice Controls – Nintex Forms | Summit 7 Systems

 

The sample form included in this asset was built using Nintex Forms for SharePoint 2013 (on-premise) in order to utilize live form submission. However, none of the techniques used in this asset are limited by the on-premise product and can be implemented in Nintex Forms for Office 365 as well.

Nintex Xchange Terms of Use Policy

Nintex makes no warranty or guarantee about the reliability, performance, quality, or functionality of any assets, and any assets you install are therefore provided as is. By downloading this asset, you agree to the terms of use.

Outcomes