What is the Motivation for this Feature?
Often, especially when an exhibit requires some form of presets, an exhibit developer needs a way to represent many instances of identically structured groups of settings. For example, imagine a simple exhibit that controls a lighting system where the goal is to change the state of the lights with different presets. Sounds simple enough; just use a DROPDOWN setting type where the user can select one of the many preconfigured presets:
{
"manifest": {
"statuses": [ ... ],
"controls": [ ... ],
"settings": [
{
"id": "lighting-presets",
"type": "Dropdown",
"display": "Lighting Preset",
"items": [
{
"id": "presetId1",
"display": "My Preset Name 1",
"order": 0
},
{
"id": "presetId2",
"display": "My Preset Name 2"
},
{
"id": "presetId3",
"display": "My Preset Name 3"
}
]
}
]
}
}
But what if an additional preset is added to the lighting system after the exhibit is installed? Then the exhibit developer must manually add this preset to the manifest:
{
"manifest": {
"statuses": [ ... ],
"controls": [ ... ],
"settings": [
{
"id": "lighting-presets",
"type": "Dropdown",
"display": "Lighting Preset",
"items": [
[...]
{
"id": "newPresetId",
"display": "My New Preset"
}
]
}
]
}
}
So if more presets need to be added post-installation, this setup will increase the technical expertise needed to update an exhibit over its lifecycle.
Settings Lists solve this problem by allowing a developer to define groups of settings that can be dynamically created after exhibit installation.
How do Settings Lists Work?
Setting Lists enable the dynamic creation of settings in the Gumband UI by following a predefined schema in the manifest. The schema of the Setting List is essentially its class definition, and it defines what settings should be present in each new setting list item. Once the schema is defined in the manifest, setting items, each of which contains each new setting defined in the schema, can be created through the Gumband UI.
Usage In-Depth
For this example, imagine an exhibit that takes a few pieces of data to configure different presets for a screen.
Defining Settings Lists in the Manifest
Settings Lists are defined in the Manifest file in a similar manner to top-level settings. The only difference is that they require an additional entry to define the schema, which is just another array of settings.
{
"manifest": {
"statuses": [ ... ],
"controls": [ ... ],
"settings": [
{
"id": "screens",
"type": "SettingsList",
"display": "Screens",
"order": 0, // optional
"schema": [ // any Gumband setting types can be included
{
"id": "bkg_img",
"type": "FileSelection",
"display": "Background Image",
"order": 0
},
{
"id": "header",
"type": "TextInput",
"display": "Header",
"order": 1
},
{
"id": "body",
"type": "TextInput",
"display": "Body",
"order": 2
}
]
},
],
}
}
Exhibit Manipulation
Once added to the manifest and with the exhibit running, the Settings List will appear as its own setting on the Settings Page. The (0) indicates that there are currently no instances of list items in the Screens SettingList. Click it to view, create, and modify list items.
Create a new setting list item by clicking the Create New button, which will open a modal.
Backend Data Flow
Upon list item creation, a new, blank instance of a Screens Setting List item called “Welcome Screen” will appear in the UI. This creation also triggers event triggers a SETTING_LIST_RECEIVED callback to be fired in the Exhibit’s NodeJS SDK application:
gb.on(Sockets.SETTING_LIST_RECEIVED, (payload) => {
console.log(payload);
});
//Prints out...
{
"id": "screens",
"value": [
{
"id": "Welcome Screen",
"value": [
{
"id": "screens/\"Welcome Screen1\"/bkg_img",
"value": null
},
{
"id": "screens/\"Welcome Screen1\"/header",
"value": null
},
{
"id": "screens/\"Welcome Screen1\"/body",
"value": null
}
]
}
]
}
The settings within the Welcome Screen list items are just like any other setting. Simply edit the fields and save.
When you click the Save button, your Exhibit’s NodeJS SDK application will receive data as shown above, through the SETTING_RECEIVED callback’s payload variable:
gb.on(Sockets.SETTING_RECEIVED, (payload) => {
console.log(payload);
});
//Prints out...
This callback is fired for each individual Setting modified, which means that if fields in more than one Setting List Instance are updated, you’ll receive them all as individual setting callbacks, in potentially any order:
{
"id": "screens/\"Welcome Screen\"/bkg_img",
"value": "[ORG] gumband_logo.png"
}
{
"id": "screens/\"Welcome Screen\"/body",
"value": "Gumband is an operating system for interactive [...]"
}
{
"id": "screens/\"Welcome Screen\"/header",
"value": "Welcome to Gumband!"
}
{
"id": "screens/\"Health\"/bkg_img",
"value": "[ORG] Gumband Health Icon.png"
}
{
"id": "screens/\"Health\"/body",
"value": "Gumband relays operational data and stats through [...]"
}
{
"id": "screens/\"Health\"/header",
"value": "Health"
}
Manual Retrieval
It is also possible to retrieve SettingList instances manually.
With two setting list items in the Screens SettingList, the following code will deliver JSON-formatted data of the SettingsList schema followed by the items themselves with all associated data.
const sl = await gb.getAllSettingLists(); console.log(JSON.stringify(sl,null, 4));
Individual Settings within each setting list item can be retrieved and modified manually as well:
const health_header = await gb.getSetting("screens/\"Health\"/header");
console.log(health_header);
// Prints out:
{
"id": 1612,
"manifestId": "screens/\"Health\"/header",
"exhibitId": 146,
"type": "TextInput",
"display": "Header",
"enabledOpMode": null,
"value": "Health",
"default": "",
"order": 1,
"touchless": null,
"listId": 67,
"items": [],
"read": true,
"write": true
}
// To update the setting's value property
await gb.setSetting("screens/\"Health\"/header", "Health: System Operational Stats");