Use Reference Data with Cascading Dropdowns

   MaestroThe UI design product.  |   Form Builder Platform Developer |  19.05 This feature was introduced in 19.05.

While building onboarding application forms, you can use various reference data to pre-fill and autocomplete form's fields, as well as validate user input against this data. Reference data is static data that is created and stored in Manager and it is pertinent to an organization, which Maestro forms, belonging to that organization, can access.

Journey Maestro allows Form Builders to access reference data using Cascading Dropdowns. For more information, see Prefill a Cascading Dropdown in Composer

To complete your reference data implementation, you need to add cascading dropdowns. Here we will add additional dropdowns for Model and Year to the form. When the value selected in the manufacturer dropdown changes, the model will be re-populated with the models available from the chosen manufacturer. Similarly, when the model dropdown selection changes, the years dropdown will be re-populated.

Because we have continued to use the 'label' and 'value' properties throughout all levels of our JSON data, we don't need to change the 'Label Field' and 'Value Field' properties on any of the dropdowns.

The instructions here relate to the initial Data Field named 'manufacturers' and Dynamic Data Dropdown called 'manufacturer'. We created these components in the JavaScript library method. If you followed the JavaScript Library instructions and saved your form, re-use that form here so that your data fields and dropdown names match these instructions.

1. Open a Maestro form, which you created using the JavaScript Library, in the Maestro editor.
2. Check the Calculation rule on the 'manufacturers' Data Field... it should already contain motorCyclesReferenceData from the JavaScript Library method instructions
3. Add 2 more Data Field components to your form, name them 'models' and 'years'
4. Add 2 more Dynamic Data Dropdown components, name them 'Model' and 'Year'
5. Change the Data Source properties of Model and Year dropdowns to the Data Fields 'models' and 'years'
6. Add a Change rule to the Manufacturer dropdown, with the code:

   var selected = data.manufacturer;
   data.manufacturers.some(function(element) {
       if (element.value === selected) {
           data.models = element.models;
           data.years = undefined;
           return true;
       }
   });
   return undefined;

7. The code above will execute when the Manufacturer dropdown selection is changed. The code just replaces the Data Fields 'models' with the child property 'models' from the selected manufacturer, and also sets 'years' to undefined.
8. At this stage, you could Publish and render your form and see the Model dropdown populates on a change of Manufacturer, but the Year dropdown is always empty. We will implement a Model Change rule to bring the Year dropdown into play.
9. Now add a Change rule to the Model dropdown, with the code:

   data.years = data.models.filter(function(element) {
       return element.value === data.model
   })[0].years;

10. The code above just sets the 'years' Data Field to the years property of the currently select model. It closely follows the Manufacturer change rule code but is implemented slightly differently to demonstrate there are different methods that can be used to achieve the same result. In this case, we use the JavaScript filter function to find the matching data from the models Data Field.
11. Save and Publish your form so you can see the cascading behavior between the Manufacturer, Model, and Year dropdowns.

Next, learn about pre-submit validation.