Selector properties

The Nested Dropdown screen defines the selectors (dropdowns), and defines options to apply to selectors. The properties on screen change depending on the element (selector or option) you are viewing or editing. These properties are available for Nested Dropdown Selectors. 

Name

Name of the selector and the label for the selector on a survey form.

Question

Question associated with the selector. There can be only one nested dropdown per question. The first selector defined for a Feedback field creates both the top-level "question" element in the hierarchy, and makes the selector a child of that element. All subsequent selectors for the same question appear as children of the same question element.

Level

Order of the selector in the dropdown. Each selector has a unique level number that is its position in the list, in descending order. The final selector — the one the picks the actual unit — is level 0 and appears last on the survey form, such as "Store Name" in the illustration below. 

Each selector must have a level. Additionally:

• There cannot be gaps in the levels; for example, you cannot have levels 0,1,3 because 2 is missing

Alt Set

The choice set of the selector, usually Unit for level zero (0), and Unit Group for all other levels.

Type

Type of selector; one of:

• NORMAL — The selector appears in the drop-down menu on the survey.
• HIDDEN — The selector does not appear in the drop-down menu on the survey. Use this for the selector that has an option with AUTO_CHILDREN to populate choices in the next selector(s).
  • There can be only one hidden selector, and it must be at a level higher than all Normal selectors.
  • The level zero (0) selector cannot be hidden.
• AUTO_OPTIONS — Populate the selector with all choice set items for the given choice set. Use this type to create a Nested dropdown with a single selector, where the selector's options provide filters that determine the choices to show in the drop-down list.

Alt name format

Label to show on the dropdown for each choice set item. By default, the label is the Name of the Units associated with the invitation. Often the Unit name is not desirable for the label, such as when it is number or a coded value. Sometimes, the desired label should be some combination of information about the Unit, such as the City+Name.

This property takes a simple JavaScript expression, and the expression recognizes a few built-in functions. For example, to display the city name of the unit (the City property of the unit), use the alt.City function: alt.City

Or, to concatenate the city and unit names: alt.city + ', ' + alt.name

To access the name of another field in the invitation record, use alt.field(). Foe example, to access a Unit data fields named u_display_name: alt.field('u_display_name')

This property accepts any JavaScript functions expression that returns a string. This example uses the display name when there is a value in the field; otherwise, it uses the name of the unit.

if ( alt.field('u_display_name') ) { 
    alt.field('u_display_name') 
    } else {alt.name}

Here are the nested drop-down functions and which type of selectors they can be used on:

Function	Result	Selector type
alt.altSetId	Alternative Set Id property of the AltSet the choice is based on	Any
alt.city	Unit City property	Unit
alt.countryState	Unit State/Country property	Unit
alt.field('<fieldName>')	Value of the named field, such as 'u_display_name'	Any selector
alt.identifier	Unit Identifier property	Unit
alt.isCountry	True when the choice is based on the Country AltSet	Any (though Unit Group is best)
alt.isEnumerated	True when data type of the choice set is based on is Choice set	Any
alt.isUnit	True when the choice set item is a Unit	Any
alt.isUnitGroup	True when the choice set item is a Unit group	Any
alt.name	Unit Name property	Unit
alt.parent	Unit Group Parent property	Unit Group
alt.streetAddress	Unit Street Address property	Unit
alt.zip	Unit Zip property	Unit

Translation explanation

Note to translators describing the Alt name format to ensure proper localization of the name or label.

Member children

When the selector is a Normal type, and the selector is not level zero (0), this property selects level-zero options to apply to this selector. Use this when the AltSet for the selector is not in the database.

Option properties

These properties are available for Nested dropdown Options. Note that Options alter or define the behavior of the associated selector.

Alt Set

Choice set of the option. The options are:

• None — Use the same AltSet as the parent selector. Once the new option is saved, this property is hidden when the AltSet is same as the parent.
• AltSet — To use in the option.

Alternative

Choice set value to use in the item; how it used depends on the Type. For example, choosing a group for a Unit group makes all alternative values for that group available to the option. When the Type is a filter, the selection is limited to all alternatives in the group (require) or excludes all alternatives in the group (exclude). When the Type is AUTO_CHILDREN, the choice set should be one in the parent AltSet.

Type

Type of the option. The choices are:

• NORMAL — Assigns choices based on the specified Alternative value.
• FILTER_REQUIRE — Show only choices matching the Alternative value, which is usually a Unit Group and the selector includes all choices in the group.
• FILTER_EXCLUDE — Exclude all unit group choices matching the Alternative value, which is usually a Unit group and the selector excludes all choices in the group.
• AUTO_CHILDREN — Generates the list of choices to make available in the subsequent selector(s). For this to work, either this option must be a Unit group and the subsequent selector(s) must also be Unit Group, finally followed by a Unit selector.

Important: FILTER_EXCLUDE only works for unit groups. To hide individual units from unit selector, create a unit group that can be hidden, such as "Closed stores".

Creating a Nested dropdown

To define a nested dropdown on the Nested Dropdowns screen:

1. First verify that a Feedback field exists for the target choice set (typically a Unit) that will answer the question.
2. Click New Nested DropDown Selector and assign these properties:
   • Name — Name of the selector
   • Question — The target Feedback field.
   • Level — Zero (0).
   • AltSet — Of the target data type, typically a Unit
3. Click Save to create the element and the selector.
4. Optionally, create options for the selector. Click the selector, then click New Nested dropdown option and assign the properties.
5. Define the additional selectors and assign them levels.
6. Verify the nested dropdown by clicking Test. This creates a nested dropdown at the bottom of the screen. 
   • Choose different selector options to verify the subsequent selectors are showing the correct values.
   • Verify the labels are the desired values (as defined by the Alt name format property).
   • When the alternative have been translated, the menu shows all the translated labels for the choice.

Translating Unit group labels

Nested dropdown selectors on surveys always show the names in US English, even when they have been translated and appear correct in the "test" version of the nested dropdown.

To localize the group names:

1. Create a Unit groups data fields to hold the English name. For example, of the group name is Country, create a data field for the display name, such as country_displayname. Be sure to use Translatable Text for the Alternative Set.
2. When importing Units, copy the Country name field to the display name field.
3. Translate the values for the display name field.
4. In the Nested Dropdown select for the Country unit group, assign an Alt name format that retrieves the display name for the group: alt.field('ug_country_displayname')

Hiding selectors

Sometimes it is desirable to hide some selectors until others have had their choices selected. Do that on the Survey Programs > Details for the Nested Dropdown survey node. On that screen, include the progressiveDisclosure parameter. When the parameter value is true, only the first selector is visible to survey takers. Once they make a selection, the next selector becomes visible

progressiveDisclosure= true

Hide specific selector levels with the hiddenLevels parameter. For example, to hide the first two levels: hiddenLevels=1,2.

To hide nested dropdowns conditionally, such as to show a full three-level dropdown for one condition and a single-level selector for another condition, create two Nested Dropdown elements that use the same Nested Dropdown question ID, hide levels in one instance but show them in the other, and conditionalize the elements.

Using a single selector dropdown

Selectors can very many options. But sometimes it is desirable to have a single dropdown instead of multiple, nested dropdown selectors. 

To create a nested dropdown with a single selector, where the selector's options provide filters that determine the choices to show in the drop-down list, use the AUTO_OPTIONS selector Type. This type of selector populates the choices with all the alternatives for the AltSet that match the option filters (if any).

Importing a hierarchy

When importing units with the Auto Importer, use the createHierarchy attribute to nest fields in the Unit groups. For example, to import units and nest the countries, cities, and states as Unit groups:

<output-column>
<target-field fieldId="acme_nested" fieldName="acme_nested" requiredness="REQUIRED" type="UNIT_GROUP">
 <unit-group-field-parse-options mappingKey="IDENTIFIER" delimiter="|" createIfMissing="true" createHierarchy="true" />
 <javascript-transform><![CDATA[
 var countryAbbr = record['country'];
 var stateAbbr = record['state']; 
 var cityName = record['city'];
 
 var countryId  = "country_" + countryAbbr;
 var stateId  = "state_" + stateAbbr;
 var cityId  = "city_" + cityName + stateAbbr;
 
 return  countryId + '|' + stateId + '|' + cityId;
 ]]></javascript-transform>
 </target-field>
</output-column>