Configuration

Chorus' API makes it easy to create Spigot-like configurations. Just call the createConfig and pass the content as a JavaScript map:

createConfig({
    'key1': 'value',
    'key2': {
        'int': 1,
        'string': 'abc'
    },
    'key3': list( // Using the list(...) function as the default js [...] operator causes errors.
        'This', 'is', 'a', 'list'
    )
});

Will generate the following:

key1: value
key2:
  int: 1
  string: abc

If the config already exists, createConfig will just load it.

If you want to load an external YAML file, call loadConfig(file), where file is either a relative path starting from add-on's folder or a File instance.

After that, it is possible to get the config instance by calling getConfig(), which gives access to the following methods:
get(key) - value as object
getInt(key) - value as integer
getBoolean(key) - value as boolean
getList(key) - value as object list
getMap(key) - value as string-to-object map
getKeys() - set of keys
set(key, value) - sets value and saves
setWithoutSaving(key, value) - sets value and does not save
store() - saves and reloads the configuration
reload() - reloads the configuration

Interacting from settings

In just one function, Chorus is able to make your configuration editable within the settings window.
It's needed to call allowSettings(true) right after createConfig.

By default this will take every key (except those starting with an underscore) and will automatically generate its own setting section.
However, you should use translations for a better text handling (see below the example).
Note that nested YAML keys are not supported.

Example:

string_example: Hello
number_example: 10
boolean_example: true
list_example:
- a
- b
- c
_this_is_not_included: abc

You can also add listeners that will be called whenever the user changes a field from settings by calling addConfigListener(key, action):

addConfigListener('string_example', () => {
    const value = getConfig().get('string_example');
    print(value);
});

Settings translation schemes

The best way to approach generated settings is internationalization.
In order to enable it just call translateConfigSettings(true) right after allowSettings(true). This will load texts from translationMap instead of having a fixed value.

Let's say your add-on has a config key named my_key, then your translationMap will contain something like this:

translationMap = {
    // ...
    'config.my_key': {
        en: 'My key',
        it: 'La mia chiave',
        de: 'Meine Taste',
    }
}

As you can see you can have a much more flexible control over key names by just adding your key preceded by config..
Remember that you don't strictly have to translate your strings to every language Chorus supports. You can even just set translations for English only that will be picked by default.

Additionally, translated settings also have descriptions support, that can't be handled with the "traditional" way.
In order to define a description just create a new translation value bound to the same as before with the .text suffix, like the following:

translationMap = {
    // ...
    'config.my_key': {
        en: 'My key',
        it: 'La mia chiave',
        de: 'Meine Taste',
    },
    'config.my_key.text': {
        en: 'This is your personal key.',
        it: 'Questa è la mia chiave personale.',
        de: 'Dies ist mein persönlicher Schlüssel.',
    }
}