ISettingsPlugin

The plugin that manages settings for the administrator or owner. The plugin that can interact with the settings panel.

Everything the plugin saves is serialized into a single string that the portal caps at 255 characters, and a longer one is refused rather than truncated. Keep the settings object to a few short scalar fields and hold anything bulkier in a file or a portal entity the plugin refers to by ID.

Example

The plugin class implements ISettingsPlugin: adminPluginSettings describes the settings block (a webhook URL input and a save button) shown in the modal window with the plugin description. ONLYOFFICE Apps calls getAdminPluginSettings to render the block and setAdminPluginSettingsValue to pass the saved value back to the plugin.

import {
  type IInput,
  type ISettings,
  type ISettingsPlugin,
  Components,
  InputSize,
  ButtonSize,
  Actions,
  ToastType,
} from "@onlyoffice/docspace-plugin-sdk";

class Plugin implements ISettingsPlugin {
  webhookUrlInput: IInput = {
    value: "",
    placeholder: "https://example.com/webhook",
    size: InputSize.base,
    scale: true,
    onChange: (value) => {
      this.webhookUrlInput.value = value;
      return {
        actions: [Actions.updateProps],
        newProps: { ...this.webhookUrlInput, value }
      };
    }
  };

  adminPluginSettings: ISettings | null = {
    settings: {
      children: [
        {
          component: Components.label,
          props: { text: "Webhook URL", isRequired: true }
        },
        {
          component: Components.input,
          props: this.webhookUrlInput
        }
      ]
    },
    saveButton: {
      component: Components.button,
      props: {
        label: "Save",
        size: ButtonSize.normal,
        primary: true,
        onClick: () => ({
          actions: [Actions.saveSettings, Actions.showToast],
          settings: JSON.stringify({ webhookUrl: this.webhookUrlInput.value }),
          toastProps: [{ type: ToastType.success, title: "Settings saved" }]
        })
      }
    }
  };

  setAdminPluginSettings = (settings: ISettings | null): void => {
    this.adminPluginSettings = settings;
  };

  setAdminPluginSettingsValue = (settings: string | null): void => {
    if (!settings) return;
    const { webhookUrl } = JSON.parse(settings);
    this.webhookUrlInput.value = webhookUrl;
  };

  getAdminPluginSettings = (): ISettings | null => {
    return this.adminPluginSettings;
  };
}

Methods

setAdminPluginSettings()

setAdminPluginSettings(settings: ISettings | null): void;

Update the administrator or owner plugin settings

Parameters

Parameter	Type
settings	ISettings | null

Returns

void

setAdminPluginSettingsValue()

setAdminPluginSettingsValue(settings: string | null): void;

The method is called on the portal side with the stored settings string, null until the first save.

Parameters

Parameter	Type
settings	string | null

Returns

void

Remarks

Called as the plugin loads and after a save through the React settings client, with getStatus re-read straight after, so a plugin can hide itself by its own configuration. A save reaches only the browser session that made it.

getAdminPluginSettings()

getAdminPluginSettings(): ISettings | null;

Get the administrator or owner plugin settings

Returns

ISettings | null

Properties

Property	Type	Description
adminPluginSettings	ISettings | null	The administrator or owner settings block that is embedded in the modal window with the plugin description