Data-Driven Dropdown Component

   MaestroPreviously known as Transact Maestro.  |   Form Builder |  5.1 & Higher This feature is related to 5.1 and higher.

Maestro provides the Data-Driven Dropdown component that allows you to build dynamic selection lists to implement various customer requirements.

Usage

  1. Open the Palette pane in the Maestro Editor.
  2. Locate the Data-Driven Dropdown component within the Input Fields folder.
  3. Drag the component into the View pane or the Wireframe.
  4. Configure the component's properties via the Properties pane under the Data-Driven Dropdown section.
  5. Check the Data Source field that holds a path to source data, which is a key to the data to be shown in the dropdown lists. Click the field to edit the path.
  6. For more information, see use cases below.

  7. Update Label Field which is set to the field in each array object to use as a label. It should not be blank. The default is label.
  8. Update Value Field which is set to the field in each array object that contains the value to include in submission XML for that option. It should not be blank. The default is value.
  9. Icon allows you to select another icon to indicate a dropdown. Ask the Template Designer if you can change this icon, as icons are typically customized in the templates.
  10. Select the Add Blank Value checkbox to add a blank value to the dropdown list.
  11. Click Save.
  12. Click Build and Render Form to see how this rule is displayed when the form is built and rendered.

Use Cases

There are several ways to configure the Data-Driven Dropdown component, but the basic steps are as follows:

  • Add a data field which stores your initial data. It is Product List In our example.
  • Add your Data-Driven Dropdown and configure it to point to a relevant JavaScript object.
  • Add the JavaScript script to your form to create this object using the string in your Data Field.

More generic steps are shown below:

  • Add a script which creates a map.
  • Add a component which uses the map.
  • Add a data field to store initial data, for example:
[
   {
      "label":"Single investor",
      "value":"singleSuper",
      "brand":"Corporate Bank"
   },
   {
      "label":"Joint investor",
      "value":"joint",
      "brand":"Corporate Bank"
   },
   {
      "label":"Single investor (non-super)",
      "value":"singleNonSuper",
      "brand":"Corporate Bank"
   },
   {
      "label":"Company investor",
      "value":"company",
      "brand":"Corporate Bank"
   },
   {
      "label":"Product A",
      "value":"p3",
      "brand":"Retail Bank"
   },
   {
      "label":"Product B",
      "value":"p4",
      "brand":"Retail Bank"
   },
   {
      "label":"Product Z",
      "value":"p5",
      "brand":"Retail Bank"
   }
]

Where the label and value pairs correspond to the Data-Driven Dropdown properties. It also includes additional property, brand, which may be used later on., but for now, consider it optional.

Tip: The following online tool is great for converting an excel file to JSON format:

http://www.csvjson.com/csv2json

When you copy and paste columns, just select a "tab" separator. Ensure that your columns have titles.

Adding a script which creates a map:

data.$MccCodes = [
  {
    "MCC": 742,
    "Description": "VETERINARY SERVICES",
    "label": "742 VETERINARY SERVICES"
  },
  {
    "MCC": 763,
    "Description": "AGRICULTURAL CO-OPS",
    "label": "763 AGRICULTURAL CO-OPS"
  },
  {
    "MCC": 780,
    "Description": "HORTICULTURAL AND LANDSCAPING SERVICES",
    "label": "780 HORTICULTURAL AND LANDSCAPING SERVICES"
  },
  {
    "MCC": 1520,
    "Description": "GENERAL CONTRACTORS",
    "label": "1520 GENERAL CONTRACTORS"
  }
];

Adding a Data-Driven Dropdown, and configuration

After dragging on a "Data-Driven Dropdown" component, configure the following:

Choose a name for the Data-Source. It needs to be unique, and you can ignore the $ symbol, it's a convention, not syntactical. We will use this name later, and in this example has been set as "data.$productData"

The Label Field and the Value Field need to map to keys in your JSON (not required to edit anything if you have used the template above)

Adding a script which creates an object out of your Data Field

At some point in form execution (normally on page transition or shoehorned into a validation script or calculation script on an unrelated field), you need to add some code to convert your field value into an object.

Do not add the code to a click script on the Data-Driven Dropdown, as the execution order of the script & other events will trip you up.

// data.productList is the field which contains the JSON string with keys and values
// data.$productData is the object which the Data-Driven Dropdown uses
// brand is an optional key in the JSON string
// data.tenant is a field which contains the name of current brand, and in this example is prefilled into the form by TM services on form render.
  
var tempData = JSON.parse(data.productList );
data.$productData = tempData.filter(function(arrValue,arrIndex,arr) {
  if (arrValue && arrValue.brand && arrValue.brand.toLowerCase().indexOf(data.tenant.toLowerCase())!=0) {
    return false;
  }
  return true;
});
return undefined;

Data-Driven Dropdown Component Based on a Repeating Component

To configure a dropdown option for each item in a repeating component:

  1. Configure the Data Source of the Data-Driven Dropdown to the data node for that repeat component.
  2. Configure the Label and Value properties to the appropriate field IDs within the repeat.
  3. The data source references the repeating block.
  4. The Label to be shown in the dropdown will be found in the field email address.
  5. The value that is included in the submission is also that of email address.
  6. Configure the repeat component.
  7. The data tab of the repeat displays the referenced id.
  8. Within the repeat, the email_address field is referenced.
  9. image 3

Data-Driven Dropdown Component Based on a Range Component

Note

You can also use this example for other generated sequence.

An array such as a range, for example years from 1900 to 2020, can be initialized as a transient data value in the Form load event, so it can be used as the Data Source for a data-driven dropdown. You can use this helper method to generate a range of values:


Calc.rangeSelection(10, 20)

Data-Driven Dropdown Component Based on Text Input

You could base the dropdown values on a text value such as an input field for testing, or the result of a dynamic data service call by converting the text to an appropriate array format. You can use this method, depending on data format, which takes a string in Composer-style comma-and-pipe delimited format and produces an array suitable for data-driven dropdowns:


Calc.delimitedSelection(data)
Note

Each option is delimited by a comma, and within the option, the Label and Value are delimited by a pipe.

Cascading Dropdowns

You can create cascading dropdowns by setting the Data Source of one to be the top level of an array, for example from a JSON source, and using its Change rule script to set a transient data value to an array nested within the top-level object. This transient data value then forms the Data Source for the second data-driven dropdown.

Next, learn about the Date Picker component.