blap/docs/settings.md

Settings Reference

This document serves as developer documentation for using "Granular Settings". Granular Settings allow users to specify different values for a setting at particular levels of interest. For example, a user may say that in a particular room they want URL previews off, but in all other rooms they want them enabled. The SettingsStore helps mask the complexity of dealing with the different levels and exposes easy to use getters and setters.

Levels

Granular Settings rely on a series of known levels in order to use the correct value for the scenario. These levels, in order of priority, are:

• device - The current user's device
• room-device - The current user's device, but only when in a specific room
• room-account - The current user's account, but only when in a specific room
• account - The current user's account
• room - A specific room (setting for all members of the room)
• config - Values are defined by the settingDefaults key (usually) in config.json
• default - The hardcoded default for the settings

Individual settings may control which levels are appropriate for them as part of the defaults. This is often to ensure that room administrators cannot force account-only settings upon participants.

Settings

Settings are the different options a user may set or experience in the application. These are pre-defined in src/settings/Settings.ts under the SETTINGS constant, and match the ISetting interface as defined there.

Settings that support the config level can be set in the config file under the settingDefaults key (note that some settings, like the "theme" setting, are special cased in the config file):

{
  ...
  "settingDefaults": {
    "settingName": true
  },
  ...
}

Getting values for a setting

After importing SettingsStore, simply make a call to SettingsStore.getValue. The roomId parameter should always be supplied where possible, even if the setting does not have a per-room level value. This is to ensure that the value returned is best represented in the room, particularly if the setting ever gets a per-room level in the future.

In settings pages it is often desired to have the value at a particular level instead of getting the calculated value. Call SettingsStore.getValueAt to get the value of a setting at a particular level, and optionally make it explicitly at that level. By default getValueAt will traverse the tree starting at the provided level; making it explicit means it will not go beyond the provided level. When using getValueAt, please be sure to use SettingLevel to represent the target level.

Setting values for a setting

Values are defined at particular levels and should be done in a safe manner. There are two checks to perform to ensure a clean save: is the level supported and can the user actually set the value. In most cases, neither should be an issue although there are circumstances where this changes. An example of a safe call is: