@jupyterlab/settingregistry

constructor

constructor(options: { schema: T });

property schema

readonly schema: ISettingRegistry.IProperty;

• The plugin's schema.

method default

default: (key?: string) => PartialJSONValue | undefined;

• Calculate the default value of a setting by iterating through the schema.

  Parameter key

  The name of the setting whose default value is calculated.

  Returns

  A calculated default JSON value for a specific setting.

method isDefault

isDefault: (user: ReadonlyPartialJSONObject) => boolean;

• Checks if any fields are different from the default value.

constructor

constructor();

• Instantiate a schema validator.

method validateData

validateData: (
    plugin: ISettingRegistry.IPlugin,
    populate?: boolean
) => ISchemaValidator.IError[] | null;

• Validate a plugin's schema and user data; populate the composite data.

  Parameter plugin

  The plugin being validated. Its composite data will be populated by reference.

  Parameter populate

  Whether plugin data should be populated, defaults to true.

  Returns

  A list of errors if either the schema or data fail to validate or null if there are no errors.

constructor

constructor(options: SettingRegistry.IOptions);

• Create a new setting registry.

property connector

readonly connector: IDataConnector<ISettingRegistry.IPlugin, string, string>;

• The data connector used by the setting registry.

property pluginChanged

readonly pluginChanged: ISignal<this, string>;

• A signal that emits the name of a plugin when its settings change.

property plugins

readonly plugins: { [name: string]: ISettingRegistry.IPlugin };

• The collection of setting registry plugins.

property ready

readonly ready: Promise<void>;

• A promise which resolves when the pre-fetched plugins passed to the registry finished pre-loading.

property schema

readonly schema: ISettingRegistry.ISchema;

• The schema of the setting registry.

property validator

readonly validator: ISchemaValidator;

• The schema validator used by the setting registry.

method get

get: (
    plugin: string,
    key: string
) => Promise<{
    composite: PartialJSONValue | undefined;
    user: PartialJSONValue | undefined;
}>;

• Get an individual setting.

  Parameter plugin

  The name of the plugin whose settings are being retrieved.

  Parameter key

  The name of the setting being retrieved.

  Returns

  A promise that resolves when the setting is retrieved.

method load

load: (
    plugin: string,
    forceTransform?: boolean
) => Promise<ISettingRegistry.ISettings>;

• Load a plugin's settings into the setting registry.

  Parameter plugin

  The name of the plugin whose settings are being loaded.

  Parameter forceTransform

  An optional parameter to force replay the transforms methods.

  Returns

  A promise that resolves with a plugin settings object or rejects if the plugin is not found.

method reload

reload: (plugin: string) => Promise<ISettingRegistry.ISettings>;

• Reload a plugin's settings into the registry even if they already exist.

  Parameter plugin

  The name of the plugin whose settings are being reloaded.

  Returns

  A promise that resolves with a plugin settings object or rejects with a list of ISchemaValidator.IError objects if it fails.

method remove

remove: (plugin: string, key: string) => Promise<void>;

• Remove a single setting in the registry.

  Parameter plugin

  The name of the plugin whose setting is being removed.

  Parameter key

  The name of the setting being removed.

  Returns

  A promise that resolves when the setting is removed.

method set

set: (plugin: string, key: string, value: JSONValue) => Promise<void>;

• Set a single setting in the registry.

  Parameter plugin

  The name of the plugin whose setting is being set.

  Parameter key

  The name of the setting being set.

  Parameter value

  The value of the setting being set.

  Returns

  A promise that resolves when the setting has been saved.

method transform

transform: (
    plugin: string,
    transforms: {
        compose?: ISettingRegistry.IPlugin.Transform;
        fetch?: ISettingRegistry.IPlugin.Transform;
    }
) => IDisposable;

• Register a plugin transform function to act on a specific plugin.

  Parameter plugin

  The name of the plugin whose settings are transformed.

  Parameter transforms

  The transform functions applied to the plugin.

  Returns

  A disposable that removes the transforms from the registry.

  #### Notes - compose transformations: The registry automatically overwrites a plugin's default values with user overrides, but a plugin may instead wish to merge values. This behavior can be accomplished in a compose transformation. - fetch transformations: The registry uses the plugin data that is fetched from its connector. If a plugin wants to override, e.g. to update its schema with dynamic defaults, a fetch transformation can be applied.

method upload

upload: (plugin: string, raw: string) => Promise<void>;

• Upload a plugin's settings.

  Parameter plugin

  The name of the plugin whose settings are being set.

  Parameter raw

  The raw plugin settings being uploaded.

  Returns

  A promise that resolves when the settings have been saved.

constructor

constructor(options: Settings.IOptions);

• Instantiate a new plugin settings manager.

property changed

readonly changed: ISignal<this, void>;

• A signal that emits when the plugin's settings have changed.

property composite

readonly composite: ReadonlyPartialJSONObject;

• The composite of user settings and extension defaults.

property id

readonly id: string;

• The plugin name.

property isDisposed

readonly isDisposed: boolean;

• Test whether the plugin settings manager disposed.

property isModified

readonly isModified: boolean;

• Whether the settings have been modified by the user or not.

property plugin

readonly plugin: ISettingRegistry.IPlugin;

property raw

readonly raw: string;

• The plugin settings raw text value.

property registry

readonly registry: ISettingRegistry;

• The setting registry instance used as a back-end for these settings.

property user

readonly user: ReadonlyPartialJSONObject;

• The user settings.

property version

readonly version: string;

• The published version of the NPM package containing these settings.

method annotatedDefaults

annotatedDefaults: () => string;

• Return the defaults in a commented JSON format.

method dispose

dispose: () => void;

• Dispose of the plugin settings resources.

method get

get: (key: string) => {
    composite: ReadonlyPartialJSONValue | undefined;
    user: ReadonlyPartialJSONValue | undefined;
};

• Get an individual setting.

  Parameter key

  The name of the setting being retrieved.

  Returns

  The setting value.

  #### Notes This method returns synchronously because it uses a cached copy of the plugin settings that is synchronized with the registry.

method remove

remove: (key: string) => Promise<void>;

• Remove a single setting.

  Parameter key

  The name of the setting being removed.

  Returns

  A promise that resolves when the setting is removed.

  #### Notes This function is asynchronous because it writes to the setting registry.

method save

save: (raw: string) => Promise<void>;

• Save all of the plugin's user settings at once.

method set

set: (key: string, value: JSONValue) => Promise<void>;

• Set a single setting.

  Parameter key

  The name of the setting being set.

  Parameter value

  The value of the setting.

  Returns

  A promise that resolves when the setting has been saved.

  #### Notes This function is asynchronous because it writes to the setting registry.

method validate

validate: (raw: string) => ISchemaValidator.IError[] | null;

• Validates raw settings with comments.

  Parameter raw

  The JSON with comments string being validated.

  Returns

  A list of errors or null if valid.

method validateData

validateData: (
    plugin: ISettingRegistry.IPlugin,
    populate?: boolean
) => ISchemaValidator.IError[] | null;

• Validate a plugin's schema and user data; populate the composite data.

  Parameter plugin

  The plugin being validated. Its composite data will be populated by reference.

  Parameter populate

  Whether plugin data should be populated, defaults to true.

  Returns

  A list of errors if either the schema or data fail to validate or null if there are no errors.

property connector

readonly connector: IDataConnector<ISettingRegistry.IPlugin, string, string>;

• The data connector used by the setting registry.

property pluginChanged

readonly pluginChanged: ISignal<this, string>;

• A signal that emits the name of a plugin when its settings change.

property plugins

readonly plugins: {
    [name: string]: ISettingRegistry.IPlugin | undefined;
};

• The collection of setting registry plugins.

property schema

readonly schema: ISettingRegistry.ISchema;

• The schema of the setting registry.

property validator

readonly validator: ISchemaValidator;

• The schema validator used by the setting registry.

method get

get: (
    plugin: string,
    key: string
) => Promise<{
    composite: PartialJSONValue | undefined;
    user: PartialJSONValue | undefined;
}>;

• Get an individual setting.

  Parameter plugin

  The name of the plugin whose settings are being retrieved.

  Parameter key

  The name of the setting being retrieved.

  Returns

  A promise that resolves when the setting is retrieved.

method load

load: (
    plugin: string,
    forceTransform?: boolean
) => Promise<ISettingRegistry.ISettings>;

• Load a plugin's settings into the setting registry.

  Parameter plugin

  The name of the plugin whose settings are being loaded.

  Parameter forceTransform

  An optional parameter to force replay the transforms methods.

  Returns

  A promise that resolves with a plugin settings object or rejects if the plugin is not found.

method reload

reload: (plugin: string) => Promise<ISettingRegistry.ISettings>;

• Reload a plugin's settings into the registry even if they already exist.

  Parameter plugin

  The name of the plugin whose settings are being reloaded.

  Returns

  A promise that resolves with a plugin settings object or rejects with a list of ISchemaValidator.IError objects if it fails.

method remove

remove: (plugin: string, key: string) => Promise<void>;

• Remove a single setting in the registry.

  Parameter plugin

  The name of the plugin whose setting is being removed.

  Parameter key

  The name of the setting being removed.

  Returns

  A promise that resolves when the setting is removed.

method set

set: (plugin: string, key: string, value: PartialJSONValue) => Promise<void>;

• Set a single setting in the registry.

  Parameter plugin

  The name of the plugin whose setting is being set.

  Parameter key

  The name of the setting being set.

  Parameter value

  The value of the setting being set.

  Returns

  A promise that resolves when the setting has been saved.

method transform

transform: (
    plugin: string,
    transforms: {
        compose?: ISettingRegistry.IPlugin.Transform;
        fetch?: ISettingRegistry.IPlugin.Transform;
    }
) => IDisposable;

• Register a plugin transform function to act on a specific plugin.

  Parameter plugin

  The name of the plugin whose settings are transformed.

  Parameter transforms

  The transform functions applied to the plugin.

  Returns

  A disposable that removes the transforms from the registry.

  #### Notes - compose transformations: The registry automatically overwrites a plugin's default values with user overrides, but a plugin may instead wish to merge values. This behavior can be accomplished in a compose transformation. - fetch transformations: The registry uses the plugin data that is fetched from its connector. If a plugin wants to override, e.g. to update its schema with dynamic defaults, a fetch transformation can be applied.

method upload

upload: (plugin: string, raw: string) => Promise<void>;

• Upload a plugin's settings.

  Parameter plugin

  The name of the plugin whose settings are being set.

  Parameter raw

  The raw plugin settings being uploaded.

  Returns

  A promise that resolves when the settings have been saved.

type DefaultMenuId

type DefaultMenuId =
    | 'jp-menu-file'
    | 'jp-menu-file-new'
    | 'jp-menu-edit'
    | 'jp-menu-help'
    | 'jp-menu-kernel'
    | 'jp-menu-run'
    | 'jp-menu-settings'
    | 'jp-menu-view'
    | 'jp-menu-tabs';

• The menu ids defined by default.

type Primitive

type Primitive = 'array' | 'boolean' | 'null' | 'number' | 'object' | 'string';

• The primitive types available in a JSON schema.

type Phase

type Phase = 'compose' | 'fetch';

• The phases during which a transformation may be applied to a plugin.

type Transform

type Transform = (plugin: IPlugin) => IPlugin;

• A function that transforms a plugin object before it is consumed by the setting registry.

function filterDisabledItems

filterDisabledItems: <T extends ISettingRegistry.IMenuItem>(items: T[]) => T[];

• Remove disabled entries from menu items

  Parameter items

  Menu items

  Returns

  Filtered menu items

function reconcileItems

reconcileItems: <T extends ISettingRegistry.IMenuItem>(
    reference?: T[],
    addition?: T[],
    warn?: boolean,
    addNewItems?: boolean
) => T[] | undefined;

• Merge two set of menu items.

  Parameter reference

  Reference set of menu items

  Parameter addition

  New items to add

  Parameter warn

  Whether to warn if item is duplicated; default to false

  Returns

  The merged set of items

function reconcileMenus

reconcileMenus: (
    reference: ISettingRegistry.IMenu[] | null,
    addition: ISettingRegistry.IMenu[] | null,
    warn?: boolean,
    addNewItems?: boolean
) => ISettingRegistry.IMenu[];

• Reconcile the menus.

  Parameter reference

  The reference list of menus.

  Parameter addition

  The list of menus to add.

  Parameter warn

  Warn if the command items are duplicated within the same menu.

  Returns

  The reconciled list of menus.

function reconcileShortcuts

reconcileShortcuts: (
    defaults: ISettingRegistry.IShortcut[],
    user: ISettingRegistry.IShortcut[]
) => ISettingRegistry.IShortcut[];

• Reconcile default and user shortcuts and return the composite list.

  Parameter defaults

  The list of default shortcuts.

  Parameter user

  The list of user shortcut overrides and additions.

  Returns

  A loadable list of shortcuts (omitting disabled and overridden).

function reconcileToolbarItems

reconcileToolbarItems: (
    reference?: ISettingRegistry.IToolbarItem[],
    addition?: ISettingRegistry.IToolbarItem[],
    warn?: boolean
) => ISettingRegistry.IToolbarItem[] | undefined;

• Merge two set of toolbar items.

  Parameter reference

  Reference set of toolbar items

  Parameter addition

  New items to add

  Parameter warn

  Whether to warn if item is duplicated; default to false

  Returns

  The merged set of items