User and System Settings Tabs API

API allows to plug your own tabs to the User Settings, the Configuration or the Workflow Settings applications.

How to export the Configuration or Workflow Settings Settings tab

You can export Configuration Settings tabs by using the configuration-settings feature,
Workflow Settings tabs by using the workflow-settings feature.

Example for Workflow Settings:

export const avid = {
    'workflow-settings': {
        'companyname-projectname-settings-tab-name': {
            config: {
                displayName: 'My System Settings',
                index: 200,
                maintainers: [{ name: 'John Doe' }],
                path: [{ displayName: 'Group 1', id: 'group1', index: 100, maintainers: [{ name: 'John Doe' }] }]
            },
            factory() {
                return new WorkflowSetting();
            }
        }
    }
};

You can also use the following approach to export Workflow Settings tabs:

export const avid = [{
        name: 'companyname-projectname-settings-tab-name',
        provides: ['workflow-settings'],
        create: () => {
            return {
                config: {
                    displayName: 'My System Settings',
                    index: 200,
                    maintainers: [{ name: 'John Doe' }],
                    path: [{ displayName: 'Group 1', id: 'group1', index: 100, maintainers: [{ name: 'John Doe' }] }]
                },
                factory() {
                    return new WorkflowSetting();
                },
            };
        }
    }
];

Use the configuration-settings feature name for Configuration Settings.

How to export the User Settings tab

You can export User Settings tabs by using the user-settings feature.

Example:

export const avid = {
    'user-settings': {
        'user-settings-tab-1': {
            config: {
                displayName: 'User settings',
                index: 100,
                maintainers: [{ name: 'Team AI' }]
            },
            factory() {
                return new UserSettings();
            }
        }
    }
};

You can also use the following approach to export User Settings tabs:

export const avid = [{
    name: 'user-settings-tab-2',
    provides: ['user-settings'],
    create: () => {
        const config = {
            config: {
                displayName: 'User Settings 1',
                index: 300,
                maintainers: [{ name: 'Team AI' }],
                path: [{ displayName: 'Group 1', id: 'group1', index: 100, maintainers: [{ name: 'Team AI' }] }, { displayName: 'Sub Group 1', id: 'subgroup1', index: 200, maintainers: [{ name: 'Team AI' }] }]
            },
            factory() {
                return new UserSettings();
            },
        };

        return config;
    }
}];

config

The config object can have the following fields:

displayName

Recommended

Localized settings tab name.
If there is no defined displayName property, it is not blocking, but it shows setting tab name as “No name”.

index

Recommended

The index property is used for tab positioning inside the parent group.
The model is merged with all other plugins and the elements are sorted by the given index.
For top-level items the index should be from 0 to 199, for second-level items from 200 to 299, for third-level items from 300 to 399, etc.
If there is no defined index property or defined incorrectly, it is not blocking, but we will not have needed sort ordering, it will be randomly sorted.

maintainers

Recommended

Array of settings tab’s maintainers names (teams).
If there is no defined maintainers property, it is not blocking, but it will be harder to notify maintainers about wrongly defined properties, for example.

path

Optional

Path specifies where the settings tab is positioned (group, subgroup).
Path is an array that contains items that describe parents of the tab from the top-level group to the subgroup.
If path is omitted, the tab is added as top-level item.

Each array item must have displayName, id, index, and maintainers.
Choose unique ids for all path parts.

Example

{
    displayName: 'My Tab',
    index: 300,
    maintainers: [{ name: 'Team AI' }],
    path: [{ displayName: 'Group 2', id: 'companyname-groupname', index: 100, maintainers: [{ name: 'Team AI' }] }, { displayName: 'Subgroup 1', id: 'companyname-groupname-subgroup1', index: 200, maintainers: [{ name: 'Team AI' }] }]
}

You can see the tab as follows:

> Group 2
    > Subgroup 1
        My Tab

Factory

Function that returns a Workflow Settings tab instance.
Instance must implement the interface described in Settings Tab API.

Settings Tab API

render

Required

Is called every time when a user selects the tab.

render({ domElement, saveHelper }) {
    // ...
}

Parameters:

{domElement} domElement where the view’s DOM structure can be appended.

{saveHelper} saveHelper - Function that can be called to save the tab.

saveHelper provides a UI helper to show the wait! saving changes and try again dialogs)

saveHelper can be used as follows:

<input type="button" value="Save" onclick='saveHelper()' />

Internally, saveHelper calls the save method of the tab.

isDirty

Optional

Must return true if a user changes settings.

isDirty():Boolean

The method can be omitted if a settings tab is used only for data preview.

save

Optional

Must return Promise that is fulfilled if settings saving is completed successfully or rejected otherwise.

save():Promise

The method can be omitted if a settings tab is used only for data preview.

destroy

Optional

destroy():void

Is called every time when a user switches to another tab or closes the whole application while the current tab is open.
Perform the necessary cleanup in this method (cancel requests, remove event listeners, etc.).