Aha! Develop | Settings extension contributions

Settings contributions give Aha! Develop users a way to customize their extensions. The settings for an extension are automatically passed to all handler callbacks in the settings value.

Click any of the following links to skip ahead:

Schema example

An extension that has a setting to configure the color of its icons would specify it in the extension package.json file:

{
"ahaExtension": {
"contributes": {
"settings": {
"color": {
"title": "Icon color",
"type": "color",
"scope": ["account", "user"],
"description": "Color of icon in records",
"default": "#000000"
}
}
}
}
}

Top

Schema

Setting

Description

type

The type can be one of boolean, color, string, or number. When the user configures the settings, they will be shown the appropriate control based on the type.

scope

Settings can be configured at the account level, the user level, or both. When a setting is configured at the account level and the user level, the extension will receive the user level setting value.

default

Settings can provide a default value, which will always be set if the setting is never configured by Aha! Develop users.

array

Any setting can be configured as an array type. This will then allow the user to specify a list rather than a single value. While this can be enabled for any setting type, it would not provide much value to have an array of booleans.

title

The title of the setting that is visible when editing the setting.

description

Additional descriptive text that is visible when editing the setting.

options

If an options key is provided, then the user is presented with a dropdown for the setting value instead of the control configured by type. Options should be an array of objects with the keys label and value:

"icon": {
"title": "Icon",
"description": "Choose the icon to display",
"scope": ["account"],
"default": "hand",
"options": [
{"label": "Hand", "value": "hand"},
{"label": "World", "value": "globe"}
]
}

Top

API

In extension callbacks, settings are passed to the props object. Using the above examples:

aha.on("viewName", ({ record, fields, onUnmounted }, { identifier, settings }) => {
settings.color; // "#000000"
settings.icon; // "hand"
})

Settings are also available on the aha object but not scoped to the extension:

aha.settings.get('my.extension.identifier.color');

This can be scoped to the extension using the identifier:

const settings = aha.settings.get('my.extension.identifier');
settings.color; // "#000000"

Top