Introduction

This control is similar to a dependent drop-down list with several differences:

The data to populate the dropdowns is provided in a JSON data structure. The JSON can be provided in the Input Control configuration in the uStore backoffice, or can be fetched from a URL allowing external systems to define the available options in the dropdown lists.

The control is designed to be flexible and is not restricted to a set number of sub lists. You can have one, two, three, or more subordinate select tags simply controlled by the input JSON.

Configuration parameters

selectTagTitles

Type: array

Example:

"selectTagTitles": ["Genre","Category","Author","Title"]

If provided, this parameter provides titles for each dropdown list. The title will appear in the first element of the relevant dropdown list like: -- Select {title} --

If the parameter is not provided, the first entry will appear like: -- Selection 1 -- with following dropdowns showing an incremental number.

selectTagData

Type: object

Example:

  "selectTagData": {
    "Fiction": {
      "Romance": ["Rebecca Yarros","Navessa Allen","Leigh Rivers"],
      "Crime & Mystery": ["David Baldacci","Candice Fox"],
      "Classic Fiction": ["Emily Bronte","Fyodor Dostoyevsky","George Orwell","John Steinbeck"],
      "Fantasy": ["Andy Weir","Alex Aster","J.R.R. Tolkien"],
      "Manga": ["Jujutsu Kaisen"]
    },
    "Non Fiction": {
      "Biographies": ["Tom Bower","Gisele Pelicot"],
      "History": ["Stephen Fry","David Mitchell"],
      "Travel": ["Lonely Planet","Jiawa Liu","Robert Pirsig"]
    }
  }

The selectTagData defines the content for the drop-down lists. Each level of the JSON defines a select tag.

In the example above, the first drop-down will have two options for "Fiction" and "Non Fiction".

The second drop-down will show the sub-options of from the JSON based on what the customer selects on the first drop-down.

Additional drop-downs can be added by adding further sub-options using the same structure.

The last drop-down will show options created from the string array.

It is not necessary for each combination to show the same number of drop-down selectors. For example some combinations can show two drop-downs, while other combinations can show 4 or more drop-downs. It is simply controlled by the JSON.

selectTagDataUrl

Type: string

Example:

"selectTagDataUrl": "https://raw.githubusercontent.com/xmpie-users/uStore-js/refs/heads/master/music.json"

If this parameter is omitted, or contains an empty string, then the selectTagData will be used.

If this parameter contains a valid URL, then the JSON will be read from the URL and the selectTagData parameter will be ignored. This is designed so that an external system can generate the required JSON - perhaps from a database query - to allow for easy update of the drop-down list options available without needing to edit the customization step each time.

useLastSelectOnly

Type: boolean

Example:

"useLastSelectOnly": false

If false the Input Control will return to uStore the value of each drop-down as it is selected. Meaning that if your selectTagData will show three drop-downs, the uStore preview will update with the value from each of the three drop-down lists as the customer makes their selections.

If true then only the last select tag will pass its value to uStore and the preview will only update when the customer makes the last selection.

Sample - data provided in the configuration

{
"selectTagTitles": ["Genre","Category","Author","Title"],
"selectTagData": {
	"Fiction": {
		"Romance": {
			"Rebecca Yarros": ["Fourth Wing","Onux Storm","Iron Flame","Wilder","Nova"],
			"Navessa Allen": ["Lights Out","Caught Up","Game On"],
			"Leigh Rivers": ["Insatiable","Voracious"]
		},
		"Crime & Mystery": {
			"David Baldacci": ["Daylignt","Nash Fals","Strangers in Time","Hope Rises","The Fix","The Target","Hells Corner"],
			"Candice Fox": ["Redbelly Crossing","Hades","Devils Kitchen"]
		},
		"Classic Fiction": {
			"Emily Bronte": ["Wuthering Heights"],
			"Fyodor Dostoyevsky": ["White Nights"],
			"George Orwell": ["1984"],
			"John Steinbeck": ["East of Eden"]
		},
		"Fantasy": {
			"Andy Weir": ["Project Hail Mary"],
			"Alex Aster": ["Starside","Lightlark","Nightbane"],
			"J.R.R. Tolkien": ["The Lord of the Rings", "The Fall of Gondolin"]
		},
		"Manga": {
			"Jujutsu Kaisen": ["Vol. 1", "Vol. 2"]
		}
	},
	"Non Fiction": {
		"Biographies": {
			"Tom Bower": ["Betrayal"],
			"Gisele Pelicot": ["A Hymn to Life"]
		},
		"History": {
			"Stephen Fry": ["Odyssey","Mythos","Heroes"],
			"David Mitchell": ["Unruly"]
		},
		"Travel": {
			"Lonely Planet": ["Japan","Australia"],
			"Jiawa Liu": ["7 Days a Parisian"],
			"Robert Pirsig": ["Zen and the Art of Motorcycle Maintenance"]
		}
	}
},
"selectTagDataUrl": "",
"useLastSelectOnly": false
}

Sample - data provided by a URL

{
  "selectTagDataUrl": "https://raw.githubusercontent.com/xmpie-users/uStore-js/refs/heads/master/music.json",
  "useLastSelectOnly": true
}

Downloads

Built versions ready to install in uStore Presets:

Subordinate Select v1

You can download and modify the source code below. To modify and build new versions follow these instructons using the source zip instead of the ng_duc_project_sample.zip:

Subordinate Select v1 Source code

Tips

• uStore v25.2 or later is required
• If your storefront shows "sorry an error occurred" when viewing a product that uses this Input Control, first check that the configuration JSON is valid by using a tool such as JSONLint
• If you experience other problems, or have suggestions for future versions, you should ask or comment on the XMPie-Users Google Group. Remember that this Input Control is not authored by XMPie, so you will probably not get support for this custom Input Control from XMPie Support.