How to Customize Your Exhibit with Configured Settings

Configuring Settings

Settings are configurations for your exhibit, and can be thought of as two way communications between the Gumband cloud and your exhibit. Settings will be the most unique between exhibits and could configure anything from text copy to the RPMs of a motor. Settings are also configured through the manifest:

{
    "manifest": {
        "statuses": [],
        "controls": [],
        "settings": [
            {
                "id": "header",
                "type": "TextInput",
                "display": "Header Copy",
                "default": "Gumband Demo",
                "order": 0
            },
            {
                "id": "subheader",
                "type": "TextInput",
                "display": "Subheader Copy",
                "default": "Digital Signage",
                "order": 1
            },
            {
                "id": "body",
                "type": "TextInput",
                "display": "Body Copy (separate by | for new paragraph)",
                "default": "Gumband is an interactive experience tool",
                "order": 2
            },
            {
                "id": "main-image",
                "type": "FileSelection",
                "display": "Image Asset",
                "order": 3
            }
        ]
    }
}

would configure settings for the following exhibit instance in the Gumband UI:

Since settings are two way communications, they can be set by the exhibit through the GumbandSDK.setSetting(settingID, newSettingValue: string | number | boolean) function in the SDK (Exhibit → Cloud), or they can be set through the Gumband UI, which can be listened for through the Sockets.SETTING_RECEIVED event listener callback (Cloud → Exhibit):

exhibitActionThatTriggersSettingChange(manifestId) {
    //where the manifestId is the "id" of the setting as set in the manifest.
    //In the example manifest above, the IDs are "header", "subheader", "body", and "main-image"
    this.gumbandSDK.setSetting(manifestId);
}
this.gumbandSDK.on(Sockets.SETTING_RECEIVED, (payload) => {
    console.log(`${payload.id} setting updated in the Gumband UI to: ${payload.value}`);
    this.updateFrontendFromSettings();
});

There are many different types of settings for various use cases. See the Exhibit Manifest Configuration doc for a complete list.

Using SettingsLists to Create Settings At Runtime

Sometimes, an exhibit will need a way to introduce more settings at runtime. This typically occurs when it needs to integrate with a variable number of similar external devices, and therefore it needs to be able to manage a variable number of a group of settings. For example, consider an exhibit that could play music from a number of sources, and suppose there was a requirement that the number of sources could change over time. Let’s assume for simplicity that these music sources are all managed by an external system (e.g. QSYS) and that all we need to know are the IDs of all of the music sources. We would start by adding a SettingsList setting type in the manifest:

{
  manifest: {
    settings: [
      {
        "id": "audio-sources",
        "type": "SettingsList",
        "display": "Audio Sources",
        "schema": [
          {
            "id": "source-id",
            "type": "TextInput",
            "display": "Source ID",
            "order": 0
          },
          {
            "id": "select-source",
            "type": "Toggle",
            "display": "Select Source",
            "order": 1
          }
        ]
      }
    ]
  }
}

This SettingsList defines a schema with two settings, a TextInput to hold the audio source ID and a Toggle to make the source the currently active music source. When the exhibit is first initialized, the Gumband UI will show a SettingsList with no items within it:

And after creating a few setting list items using the “New” button in the top right:

Using SettingsLists, our exhibit can handle any number of new audio sources in the future. However, while SettingsLists are useful, managing them in code can be cumbersome, since the names of each setting list item (“Bluetooth” and “Music Player 1” in the screenshot above) aren’t known at initialization. Furthermore, the “Source ID” and “Select Source” settings are nested within the setting list items, which means we cannot simply update the setting with a simple this.gumbandSDK.setSetting('select-source', value) call, since Gumband won’t be able to tell whether the Bluetooth “select-source” or the Music Player 1 “select-source” is being referenced. Instead, the IDs of settings within a setting list are written as follows: settingListId/"settingListItemName"/settingId. For the Bluetooth “select-source” setting this ID would be written as audio-sources/"Bluetooth"/select-source, and the value of that setting could be set from the exhibit by calling this.gumbandSDK.setSetting('audio-sources/"Bluetooth"/select-source', value). To facilitate managing the names of the list items, which cannot be hardcoded into the exhibit as they can be dynamically created in the Gumband UI, the Gumband SDK provides some helper functions. If the exhibit needs to set the values of settings in SettingsLists, we recommend the following pattern:

this.gumbandSDK.on(SOCKETS.SETTING_LIST_RECEIVED, () => {
  //This event will be emit whenever a new setting list item is created, 
  //destroyed, or updated in the Gumband UI.

  //Create a mapping between the source-id, which the external device recognizes,
  //and the list item name, which is in a human-readable format.
  //The map should be of the form: 
  // {
  //    bluetoothDeviceId: "Bluetooth", 
  //    musicPlayerDeviceId: "Music Player 1" 
  // }
});

//A function to be called when the music source is changed by some external service.
selectSource(sourceId) {
  const listItemNames = this.gumbandSDK.getSettingListItemNames('audio-sources');
  console.log(listItemNames); // ['Bluetooth', 'Music Player 1']
  
  this.sdk.setSetting(`audio-source/"${this.musicSourceMap(sourceId)}"/select-source`, true);
}