Settings

Settings

Get and set settings with server, channel, and user scope. Settings can be accessed via Monochrome#getSettings. Settings are specified by creating an array of SettingsCategorys and Settings in a javascript file and passing the path to that file into the Monochrome constructor. For a simple example of a settings definition file, see the monochrome demo. For a more advanced example, see Kotoba's settings definition file. For an example of using the settings module, see the monochrome demo settings command. The demo settings command can be used in your bot. Just edit the configuration section at the top. If you use the demo settings command, you may never need to interact with the settings module directly.

Members

(static, constant) UpdateRejectionReason :string

Description:
  • Strings describing why a setting update failed.
Source:
Properties:
Name Type Description
NOT_ADMIN string
INVALID_VALUE string
SETTING_DOES_NOT_EXIST string
NOT_ALLOWED_IN_SERVER string
NOT_ALLOWED_IN_CHANNEL string
NOT_ALLOWED_FOR_USER string
Strings describing why a setting update failed.
Type:
  • string

Methods

getInternalSettingValue(settingUniqueId, serverId, channelId, userId) → {Object|undefined}

Description:
  • Get the internal value for a setting given the current server, channel, and user context. If there's a matching user setting value, it overrides any matching channel setting value, which overrides any matching server setting value. If there are no server, channel, or user settings values set, the default value specified in the settings definition is returned.
Source:
Parameters:
Name Type Description
settingUniqueId string
serverId string The ID of the server where the setting is being accessed.
channelId string The ID of the channel where the setting is being accessed.
userId string The ID of the user using the setting.
Returns:
The internal value of the setting, or undefined if no setting is found.
Type
Object | undefined

getRawSettingsTree() → {Array.<Object>}

Description:
  • Get the settings tree that you specified in your settings file. It may not be exactly the same due to the application of default values.
Source:
Returns:
The array of settings at the root.
Type
Array.<Object>

getTreeNodeForUniqueId(uniqueId) → {Object|undefined}

Description:
  • Get the setting or category with the specified unique ID, or undefined if it doesn't exist.
Source:
Parameters:
Name Type Description
uniqueId string
Returns:
Type
Object | undefined

(async) getUserFacingSettingValue(settingUniqueId, serverId, channelId, userId) → {string|undefined}

Description:
  • Get the user facing value for a setting given the current server, channel, and user context. If there's a matching user setting value, it overrides any matching channel setting value, which overrides any matching server setting value. If there are no server, channel, or user settings values set, the default value specified in the settings definition is returned.
Source:
Parameters:
Name Type Description
settingUniqueId string
serverId string The ID of the server where the setting is being accessed.
channelId string The ID of the channel where the setting is being accessed.
userId string The ID of the user using the setting.
Returns:
The user facing value of the setting, or undefined if no setting is found.
Type
string | undefined

(async) resetServerAndChannelSettings(userId)

Description:
  • Reset all settings (both server-wide and channel-specific settings) in a server.
Source:
Parameters:
Name Type Description
userId string The ID for the user to reset settings for.

(async) resetUserSettings(userId)

Description:
  • Reset all settings for a user.
Source:
Parameters:
Name Type Description
userId string The ID for the user to reset settings for.

(async) setChannelSettingValue(settingUniqueId, serverId, channelId, newUserFacingValue, userIsServerAdmin) → {Settings~SettingUpdateResult}

Description:
  • Set a setting value for a channel.
Source:
Parameters:
Name Type Description
settingUniqueId string
serverId string The ID of the server where the setting is being set.
channelId string The ID of the channel where the setting is being set.
newUserFacingValue string The user facing value of the new setting value.
userIsServerAdmin boolean Whether or not the user is a server admin.
Returns:
The result of the attempt to update the setting.
Type
Settings~SettingUpdateResult

(async) setServerWideSettingValue(settingUniqueId, serverId, newUserFacingValue, userIsServerAdmin) → {Settings~SettingUpdateResult}

Description:
  • Set a setting value server wide. This also wipes out any channel settings in the server for the setting with the specified unique ID. User settings are unaffected.
Source:
Parameters:
Name Type Description
settingUniqueId string
serverId string The ID of the server where the setting is being set.
newUserFacingValue string The user facing value of the new setting value.
userIsServerAdmin boolean Whether or not the user is a server admin.
Returns:
Type
Settings~SettingUpdateResult

(async) setUserSettingValue(settingUniqueId, userId, newUserFacingValue) → {Settings~SettingUpdateResult}

Description:
  • Set a setting value for a user.
Source:
Parameters:
Name Type Description
settingUniqueId string
userId string The ID of the server to set the setting value for.
newUserFacingValue string The user facing value of the new setting value.
Returns:
The result of the attempt to update the setting.
Type
Settings~SettingUpdateResult

(async) userFacingValueIsValidForSetting(setting, userFacingValue) → {boolean}

Description:
  • Check if a user facing value is valid for a setting.
Source:
Parameters:
Name Type Description
setting Object The setting, found by calling getTreeNodeForUniqueId or by traversing the settings tree accessed via the getRawSettingsTree method.
userFacingValue string The user facing value to check for validity.
Returns:
Type
boolean

Type Definitions

Setting

Description:
  • Represents one setting
Source:
Properties:
Name Type Attributes Default Description
userFacingName string The name of the setting
description string A description of the setting
allowedValuesDescription string A description of what values the setting allows.
uniqueId string A unique ID for the setting. Can be anything, and should not be changed.
defaultUserFacingValue string The default user facing (string) value of the setting.
userSetting boolean <optional>
 true Whether the setting can be applied on a user-by-user basis.
channelSetting boolean <optional>
 true Whether the setting can be applied on a channel-by-channel basis.
serverSetting boolean <optional>
 true Whether the setting can be applied server-wide.
convertUserFacingValueToInternalValue function <optional>
 A function that takes a user facing string value and returns the value you want to use and store internally. If omitted, no such conversion is performed.
convertInternalValueToUserFacingValue function <optional>
 A function that takes an internal value and returns a user facing string value. If omitted, the internal value is simply stringified if not already a string.
validateInternalValue function <optional>
 A function that takes an internal setting value and returns true if it's valid, false if it's not. If omitted, not validation is performed.
Represents one setting
Type:
  • Object

SettingUpdateResult

Description:
  • The result of an attempted setting update.
Source:
Properties:
Name Type Attributes Description
accepted boolean Whether or not the update was applied.
setting Object <optional>
 The setting that was (or wasn't) updated (only present if a matching setting was found)
reason Settings.UpdateRejectionReason <optional>
 Why the update failed (only present if accepted is false)
rejectedUserFacingValue string <optional>
 The user facing value that was rejected (only present if reason === UpdateRejectionReason.INVALID_VALUE)
nonExistentUniqueId string <optional>
 The unique ID that the caller tried to change the setting value for (only present if reason === UpdateRejectionReason.SETTING_DOES_NOT_EXIST)
newUserFacingValue string <optional>
 The new user facing value that the setting was updated to (only if accepted === true)
newInternalValue string <optional>
 The new internal value that the setting was updated to (only if accepted === true)
The result of an attempted setting update.
Type:
  • Object

SettingsCategory

Description:
  • Represents a category of settings
Source:
Properties:
Name Type Description
userFacingName string The name of the category
children Array.<(Settings~SettingsCategory|Settings~Setting)> An array of child categories, or settings leafs.
Represents a category of settings
Type:
  • Object