Config

Summary

Used to access all of Mailspring's configuration details.

An instance of this class is always available as the AppEnv.config global.

Getting and setting config settings.

# Note that with no value set, ::get returns the setting's default value.
AppEnv.config.get('my-package.myKey') # -> 'defaultValue'

AppEnv.config.set('my-package.myKey', 'value')
AppEnv.config.get('my-package.myKey') # -> 'value'

You may want to watch for changes. Use observe to catch changes to the setting.

AppEnv.config.set('my-package.myKey', 'value')
AppEnv.config.observe 'my-package.myKey', (newValue) ->
  # `observe` calls immediately and every time the value is changed
  console.log 'My configuration changed:', newValue

If you want a notification only when the value changes, use onDidChange.

AppEnv.config.onDidChange 'my-package.myKey', ({newValue, oldValue}) ->
  console.log 'My configuration changed:', newValue, oldValue

Value Coercion

Config settings each have a type specified by way of a schema. For example we might an integer setting that only allows integers greater than 0:

# When no value has been set, `::get` returns the setting's default value
AppEnv.config.get('my-package.anInt') # -> 12

# The string will be coerced to the integer 123
AppEnv.config.set('my-package.anInt', '123')
AppEnv.config.get('my-package.anInt') # -> 123

# The string will be coerced to an integer, but it must be greater than 0, so is set to 1
AppEnv.config.set('my-package.anInt', '-20')
AppEnv.config.get('my-package.anInt') # -> 1

Defining settings for your package

Define a schema under a config key in your package main.

module.exports =
  # Your config schema
  config:
    someInt:
      type: 'integer'
      default: 23
      minimum: 1

  activate: (state) -> # ...
  # ...

Config Schemas

We use json schema which allows you to define your value's default, the type it should be, etc. A simple example:

# We want to provide an `enableThing`, and a `thingVolume`
config:
  enableThing:
    type: 'boolean'
    default: false
  thingVolume:
    type: 'integer'
    default: 5
    minimum: 1
    maximum: 11

The type keyword allows for type coercion and validation. If a thingVolume is set to a string '10', it will be coerced into an integer.

AppEnv.config.set('my-package.thingVolume', '10')
AppEnv.config.get('my-package.thingVolume') # -> 10

# It respects the min / max
AppEnv.config.set('my-package.thingVolume', '400')
AppEnv.config.get('my-package.thingVolume') # -> 11

# If it cannot be coerced, the value will not be set
AppEnv.config.set('my-package.thingVolume', 'cats')
AppEnv.config.get('my-package.thingVolume') # -> 11

Supported Types

The type keyword can be a string with any one of the following. You can also chain them by specifying multiple in an an array. For example

config:
  someSetting:
    type: ['boolean', 'integer']
    default: 5

# Then
AppEnv.config.set('my-package.someSetting', 'true')
AppEnv.config.get('my-package.someSetting') # -> true

AppEnv.config.set('my-package.someSetting', '12')
AppEnv.config.get('my-package.someSetting') # -> 12

string

Values must be a string.

config:
  someSetting:
    type: 'string'
    default: 'hello'

integer

Values will be coerced into integer. Supports the (optional) minimum and maximum keys.

  config:
    someSetting:
      type: 'integer'
      default: 5
      minimum: 1
      maximum: 11

number

Values will be coerced into a number, including real numbers. Supports the (optional) minimum and maximum keys.

config:
  someSetting:
    type: 'number'
    default: 5.3
    minimum: 1.5
    maximum: 11.5

boolean

Values will be coerced into a Boolean. 'true' and 'false' will be coerced into a boolean. Numbers, arrays, objects, and anything else will not be coerced.

config:
  someSetting:
    type: 'boolean'
    default: false

array

Value must be an Array. The types of the values can be specified by a subschema in the items key.

config:
  someSetting:
    type: 'array'
    default: [1, 2, 3]
    items:
      type: 'integer'
      minimum: 1.5
      maximum: 11.5

object

Value must be an object. This allows you to nest config options. Sub options must be under a properties key

config:
  someSetting:
    type: 'object'
    properties:
      myChildIntOption:
        type: 'integer'
        minimum: 1.5
        maximum: 11.5

color

Values will be coerced into a {Color} with red, green, blue, and alpha properties that all have numeric values. red, green, blue will be in the range 0 to 255 and value will be in the range 0 to 1. Values can be any valid CSS color format such as #abc, #abcdef, white, rgb(50, 100, 150), and rgba(25, 75, 125, .75).

config:
  someSetting:
    type: 'color'
    default: 'white'

Other Supported Keys

enum

All types support an enum key. The enum key lets you specify all values that the config setting can possibly be. enum must be an array of values of your specified type. Schema:

config:
  someSetting:
    type: 'integer'
    default: 4
    enum: [2, 4, 6, 8]

Usage:

AppEnv.config.set('my-package.someSetting', '2')
AppEnv.config.get('my-package.someSetting') # -> 2

# will not set values outside of the enum values
AppEnv.config.set('my-package.someSetting', '3')
AppEnv.config.get('my-package.someSetting') # -> 2

# If it cannot be coerced, the value will not be set
AppEnv.config.set('my-package.someSetting', '4')
AppEnv.config.get('my-package.someSetting') # -> 4

title and description

The settings view will use the title and description keys to display your config setting in a readable way. By default the settings view humanizes your config key, so someSetting becomes Some Setting. In some cases, this is confusing for users, and a more descriptive title is useful.

Descriptions will be displayed below the title in the settings view.

config:
  someSetting:
    title: 'Setting Magnitude'
    description: 'This will affect the blah and the other blah'
    type: 'integer'
    default: 4

Note: You should strive to be so clear in your naming of the setting that you do not need to specify a title or description!

Best practices

  • Don't depend on (or write to) configuration keys outside of your keypath.

Instance Methods

observe(keyPathcallback)

Add a listener for changes to a given key path. This is different than onDidChange in that it will immediately call your callback with the current value of the config entry. ### Examples You might want to be notified when the themes change. We'll watch `core.themes` for changes ```coffee AppEnv.config.observe 'core.themes', (value) -> # do stuff with value ```

Parameters

Argument Description
keyPath {String} name of the key to observe
callback {Function} to call when the value of the key changes.

Returns

Return Values
Returns a {Disposable} with the following keys on which you can call `.dispose()` to unsubscribe.

onDidChange([keyPath]callback)

Add a listener for changes to a given key path. If `keyPath` is not specified, your callback will be called on changes to any key.

Parameters
Argument Description
keyPath Optional {String} name of the key to observe.
callback {Function} to call when the value of the key changes.

Returns

Return Values
Returns a {Disposable} with the following keys on which you can call `.dispose()` to unsubscribe.

get(keyPath)

Retrieves the setting for the given key. ### Examples You might want to know what themes are enabled, so check `core.themes` ```coffee AppEnv.config.get('core.themes') ```

Parameters
Argument Description
keyPath The {String} name of the key to retrieve.

Returns

Return Values
Returns the value from Mailspring's default settings, the user's configuration file in the type specified by the configuration schema.

set(keyPathvalue)

Sets the value for a configuration setting. This value is stored in Mailspring's internal configuration file. ### Examples You might want to change the themes programmatically: ```coffee AppEnv.config.set('core.themes', ['ui-light', 'my-custom-theme']) ```

Parameters
Argument Description
keyPath The {String} name of the key.
value The value of the setting. Passing `undefined` will revert the setting to the default value.

Returns

Return Values
Returns a {Boolean} * `true` if the value was set. * `false` if the value was not able to be coerced to the type specified in the setting's schema.

unset(keyPath[options])

Restore the setting at `keyPath` to its default value.

Parameters
Argument Description
keyPath The {String} name of the key.
options Optional {Object}

getSchema(keyPath)

Retrieve the schema for a specific key path. The schema will tell you what type the keyPath expects, and other metadata about the config option.

Parameters

Argument Description
keyPath The {String} name of the key.

Returns

Return Values
Returns an {Object} eg. `{type: 'integer', default: 23, minimum: 1}`.
Returns `null` when the keyPath has no schema specified.

transact(callback)

Suppress calls to handler functions registered with onDidChange and observe for the duration of `callback`. After `callback` executes, handlers will be called once if the value for their key-path has changed.

Parameters
Argument Description
callback {Function} to execute while suppressing calls to handlers.

results matching ""

    No results matching ""