Settings

Settings can be used to customize the user experience. They can be edited in Atoti Admin. Unlike for permissions, individual users can edit their own settings from the UI using the Settings popup. See CoreSettings for the full list of available settings.

Update a user's settings

To change the settings of an individual user, follow these steps:

• Open Atoti Admin. If you do not know how to, please contact the support.
• Open the file named settings in the folder ui/users/<username> or create it if it does not exist.
  • To create it, right click the folder in the tree and click Create File.
• Edit it and press Ctrl/Cmd + S to save. The format of this file is JSON. Below is an example:

{
  "homePageLayout": "list",
  "dataModel.isSimplified": true
}

• Ask the user to refresh.

note

The user needs to have access to this file. To make sure they do, right-click the file in the tree and click "properties". A popup will open. The name of the user must be in Owners and Readers.

Update everyone's settings

Default settings can be created for all users in your organization at once. To do it, edit the file named organization_settings in the folder ui. This file shares the same format as individual user settings files (see above). Note that to be taken into account, it must have ROLE_USER in its readers.

Consume settings

The useSetting hook allows to consume the value of a setting in a React component. For instance, here is how to consume the value of the table.defaultSize setting:

import { useSetting } from "@activeviam/atoti-ui-sdk";

const MyComponent = () => {
  const [tableSize] = useSetting("table.defaultSize");
};

Note that the hook also returns a function to update the value of this setting, and whether the setting is currently being loaded from the server. If necessary, you can access these as follows:

const [tableSize, updateTableSize, { isLoading }] =
  useSetting("table.defaultSize");

Extend settings

Atoti UI extensions can register their own settings to customize the user experience. To add a custom setting, first you must create a setting definition. For instance:

import { SettingDefinition } from "@activeviam/atoti-ui-sdk";

const mySelectSetting: SettingDefinition<"my.feature.option"> = {
  key: "my.feature.option",
  type: "select",
  defaultValue: "one",
  options: ["one", "two", "three"],
  mode: "single",
  translations: {
    "en-US": {
      description: "The chosen option for my feature",
      title: "My option",
    },
  },
};

const myInputSetting: SettingDefinition<"my.feature.text"> = {
  key: "my.feature.text",
  type: "input",
  defaultValue: "hello world!",
  translations: {
    "en-US": {
      description: "The text setting for my feature",
      title: "My text",
    },
  },
};

const mySettings = [mySelectSetting, myInputSetting];

note

Users can search for settings by their titles, but you can also add search tokens for your settings if you want them to be matched by more search inputs:

const myInputSetting: SettingDefinition<"my.feature.text"> = {
+ searchTokens: ["hello", "world"],
};

Then register these setting definitions in your extension's activate function:

import { ExtensionModule } from "@activeviam/atoti-ui-sdk";

const extension: ExtensionModule = {
  activate: async (configuration) => {
    configuration.settings.push(...mySettings);
  },
};

This makes your settings accessible to your users and editable in the Settings popup. And you can consume them via the useSetting hook as described above.

warning

If you are using TypeScript, calling useSetting as shown above will throw an error. The section below shows how to fix it.

Typing

In order to avoid the error thrown by TypeScript when calling useSetting to retrieve the value of an extension setting, we need to create the TypeScript type representing the settings of our application (including the ones registered by our extension). It is done by leveraging the ExtendedSettings type as follows:

import { ExtendedSettings } from "@activeviam/atoti-ui-sdk";

export type MySettings = ExtendedSettings<typeof mySettings>;

Then we must pass this type when calling useSetting:

const [myOption] = useSetting<MySettings, "my.feature.option">(
  "my.feature.option",
);

This fixes the error and also types our variable myOption appropriately.

Group settings

Settings can be grouped together in a single section within the Settings popup. This is particularly useful in order to group together several settings that are relevant to a single feature. You might have noticed that this is even leveraged for core Atoti UI settings related to table widgets and to smart filtering.

To group settings together, you can create a SettingsGroup:

import { SettingsGroup } from "@activeviam/atoti-ui-sdk";

const mySettingsGroup: SettingsGroup = {
  key: "my.feature",
  settings: mySettings,
  type: "group",
  translations: {
    "en-US": {
      description: "Settings of my feature",
      title: "My feature",
    },
  },
};

note

You can also make your group act as a setting of its own, using the hasCheckbox and defaultValue attributes of SettingsGroup. This will turn the title of your setting group into a checkbox within the Settings popup, allowing users to switch the whole feature on or off easily.

const mySettingsGroup: SettingsGroup = {
+ hasCheckbox: true,
+ defaultValue: true,
};

tip

If you group settings together, we recommend that the keys of the settings in the group start by the key of the group. This increases clarity and avoids the risk that keys of your settings clash with those from a different extension. Setting keys must be unique.