enki/blap

Files

T

Travis Ralston d8a939df5d Use & enforce snake_case naming convention on config.json settings (#8062 )

* Document and support the established naming convention for config opts

This change:
* Rename `ConfigOptions` to `IConfigOptions` to match code convention/style, plus move it to a dedicated file
* Update comments and surrounding documentation
* Define every single documented option (from element-web's config.md)
* Enable a linter to enforce the convention
* Invent a translation layer for a different change to use
* No attempt to fix build errors from doing this (at this stage)

* Add demo of lint rule in action

* Fix all obvious instances of SdkConfig case conflicts

* Fix tests to use SdkConfig directly

* Add docs to make unset() calling safer

* Appease the linter

* Update documentation to match snake_case_config

* Fix more instances of square brackets off SdkConfig

2022-03-18 10:12:36 -06:00

12 KiB

Raw Blame History

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 setting_defaults 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.tsx 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 setting_defaults key (note that some settings, like the "theme" setting, are special cased in the config file):

{
  ...
  "setting_defaults": {
    "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:

const isSupported = SettingsStore.

12 KiB Raw Blame History