Settings Lists
The code referenced in this doc was written with Node.js in mind but is relevant to all provided SDKs.
Motivation
Often when an exhibit requires some form of presets, the developer will need 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:
export const MANIFEST = {
manifest: {
statuses: [ ... ],
controls: [ ... ],
settings: [
{
id: "lighting-presets",
type: "Dropdown",
display: "Lighting Preset",
items: [
{
id: "morning",
display: "Morning",
order: 0
},
{
id: "afternoon",
display: "afternoon"
},
{
id: "evening",
display: "Evening"
}
]
}
]
}
}
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:
export const MANIFEST = {
manifest: {
statuses: [ ... ],
controls: [ ... ],
settings: [
{
id: "lighting-presets",
type: "Dropdown",
display: "Lighting Preset",
items: [
[...]
{
id: "after-hours",
display: "After Hours"
}
]
}
]
}
}
So if more presets need to be added post-installation, this setup requires a considerable effort to update the exhibit over its lifecycle.
Settings Lists solve this problem by allowing a developer to define groups of settings that can be dynamically created and modified after exhibit installation.
How do Settings Lists Work?
Settings Lists enable the dynamic creation of settings in the Gumband UI by following a pre-defined schema in the manifest. The schema of the Settings List is essentially the class definition of each item the Settings List contains, which defines the Setting fields and types that should be present in each new Settings List item instance. Once the schema is defined in the manifest, Settings List item instances can be manipulated through the Gumband UI. When these instances are created, modified, or deleted, the Gumband platform sends signals to the exhibit’s SDK with the updated changes.
In-Depth Usage
For this example, imagine an exhibit that takes a few pieces of data to configure different presets for a Digital Signage display.
Manifest Settings List Implementation
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 property to define the schema: an array of settings.
export const MANIFEST = {
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. Click it to view, create, and modify list items.
An empty settings list
Create a new Settings List item by clicking the + New button, which will open a modal.
Creating a new Settings List item named “Welcome Screen” through the Settings List Item Creation modal.
Backend Data Flow
Upon list item creation, a new, blank instance of a Screens Settings List item called “Welcome Screen” will appear in the UI. This creation also triggers a SETTING_LIST_RECEIVED callback to be fired in the Exhibit’s 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.
The newly created “Welcome Screen” Settings List item instance with modified fields.
When you click the Save button, your Exhibit’s 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...
Three separate payloads received via the SETTING_RECEIVED callback.
This callback is fired for each individual Setting modified, which means that if fields in more than one Settings List item instance are updated, you’ll receive them all as individual setting callbacks, in potentially any order:
Saving both settings list item instances at once triggers a SETTING_RECEIVED callback for each Setting modified within them (six total in this case). See below for a console output of each setting’s payload received.
{
"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 SettingsList instances manually.
With two Settings List items in the Screens SettingsList, 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));
Outputs:
[
{
"id": 67,
"exhibitId": 146,
"manifestId": "screens",
"listDisplay": "Screens",
"listParent": null,
"schema": [
{
"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
}
],
"listItemCount": 2,
"order": [
"Welcome Screen",
"Health"
],
"orderSelf": 0,
"groupId": null,
"settinglistitems": [
{
"listName": "Welcome Screen",
"items": [
{
"id": 1611,
"manifestId": "screens/\"Welcome Screen\"/bkg_img",
"exhibitId": 146,
"type": "FileSelection",
"display": "Background Image",
"enabledOpMode": null,
"value": "[ORG] gumband_logo.png",
"default": "",
"order": 0,
"touchless": null,
"listId": 67,
"items": [],
"read": true,
"write": true
},
{
"id": 1610,
"manifestId": "screens/\"Welcome Screen\"/body",
"exhibitId": 146,
"type": "TextInput",
"display": "Body",
"enabledOpMode": null,
"value": "Gumband is an operating system for interactive [...]",
"default": "",
"order": 2,
"touchless": null,
"listId": 67,
"items": [],
"read": true,
"write": true
},
{
"id": 1609,
"manifestId": "screens/\"Welcome Screen\"/header",
"exhibitId": 146,
"type": "TextInput",
"display": "Header",
"enabledOpMode": null,
"value": "Welcome to Gumband!",
"default": "",
"order": 1,
"touchless": null,
"listId": 67,
"items": [],
"read": true,
"write": true
}
]
},
{
"listName": "Health",
"items": [
{
"id": 1614,
"manifestId": "screens/\"Health\"/bkg_img",
"exhibitId": 146,
"type": "FileSelection",
"display": "Background Image",
"enabledOpMode": null,
"value": "[ORG] Gumband Health Icon.png",
"default": "",
"order": 0,
"touchless": null,
"listId": 67,
"items": [],
"read": true,
"write": true
},
{
"id": 1613,
"manifestId": "screens/\"Health\"/body",
"exhibitId": 146,
"type": "TextInput",
"display": "Body",
"enabledOpMode": null,
"value": "Gumband relays operational data and stats through [...]",
"default": "",
"order": 2,
"touchless": null,
"listId": 67,
"items": [],
"read": true,
"write": true
},
{
"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
}
]
}
],
"type": "SettingsList",
"strapiContent": [],
"settingLists": [],
"settingGroups": [],
"settings": []
}
]
Individual Settings within each settings list item can be retrieved and modified manually as well:
Example
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");
With these callbacks and access functions provided by the SDK, you can respond to setting changes in real time or retrieve and update the List elements as a single-point-of-truth.