Persisting Controller State

There are a number of cases where you will need to save the state of a controller:

• You want to run the controller in an external browser but want the settings in the browser instance to be the same as the one in the Captivate UI

• You want to have the settings loaded whenever you open the same project

• You want to have the settings loaded whenever you add this controller to any project

The following methods are available for that:

saveSettings method

Store an input-specific settings string with the project.

// callback method
ServiceHandler.scheduler.saveSettings(inputName, settingsString, callback);

// promises method
await ServiceHandler.scheduler.saveSettings(inputName, settingsString);

• inputName: Name of the input that should hold the settings (can be anything for short-term settings, but must match the name of an attached input for it to be saved with the project).

• settingsString: String value to store.

• callback: This function will always be called with a single null argument

Example:

let settings = {
  version: 1,
  showColors: true,
  myLabel: 'Hello, World',
};

// note the use of JSON.stringify here
ServiceHandler.scheduler.saveSettings('Simple HTML Input', JSON.stringify(settings));

loadSettings method

Load an input-specific settings string that was saved with the project.

// callback method
ServiceHandler.scheduler.loadSettings(inputName, callback);

// promises method
await ServiceHandler.scheduler.loadSettings(inputName);

• inputName: Input behavior name matching the defintion XML.

• callback: Function with a single argument that will receive the settings string once it is retrieved.

Example:

ServiceHandler.scheduler.loadSettings('Simple HTML Input', (settingsString) => {
  try {
    let settings = JSON.parse(settingsString);
    // process settings
  } catch (e) {
    // handle JSON parsing errors here.
  }
});

saveGlobal method

Save a string of data to the Captivate system so it can be used by any controller in any project.

// callback method
ServiceHandler.scheduler.saveGlobal(settingsKey, settingsString, callback);

// promises method
await ServiceHandler.scheduler.saveGlobal(settingsKey, settingsString);

• settingsKey: The key used to identify this settings string in the global settings database.

• settingsString: String value to store.

Example:

const globalSettingsName = 'My Controller: Globals';
const settings = {
  version: 1,
  showColors: true,
  myLabel: 'Hello, World',
};

// note the use of JSON.stringify here
ServiceHandler.scheduler.saveGlobal(globalSettingsName, JSON.stringify(settings));

loadGlobal method

Load a settings string that was saved to the global settings with a specific key.

// callback method
ServiceHandler.scheduler.loadGlobal(settingsKey, callback);

// promises method
await ServiceHandler.scheduler.loadGlobal(settingsKey);

• key: The key used to identify this settings string in the global settings database.

Example:

const globalSettingsName = 'My Controller: Globals';
const settingsString = await ServiceHandler.scheduler.loadSettings(globalSettingsName);
try {
  let settings = JSON.parse(settingsString);
  // process settings
} catch (e) {
  // handle JSON parsing errors here.
}