Utils

Utility types for plugin messaging, return values, and panel navigation.

IPostMessage

The properties that are used to send a message to a frame. If the frame ID is not specified or the frame with such an ID does not exist, then nothing changes.

Example

Document preview frame communication

const previewMessage: IPostMessage = {
  frameId: "document-preview-frame",
  message: {
    action: "zoom",
    scale: 1.5,
    position: { x: 100, y: 200 }
  }
};

Properties

Property	Type	Description
frameId	string	Defines the frame ID
message	{ [key: string]: any; }	Defines a message that will be sent to a frame

---

IMessage

A message which is returned when any item interacts with a user (onClick, onChange, onSelect, etc.).

Examples

Form submission with validation and toast notification

const formSubmissionMessage: IMessage = {
  actions: [Actions.updateProps, Actions.showToast, Actions.updateContext],
  newProps: {
    type: "input",
    id: "email-input",
    value: "user@example.com",
    isDisabled: true
  },
  toastProps: [{
    type: ToastType.success,
    title: "Your data has been saved successfully"
  }],
  contextProps: [{
    name: "submit-button",
    props: {
      type: "button",
      label: "Submitted",
      isDisabled: true
    }
  }]
};

Dynamic form field updates with error handling

const fieldUpdateMessage: IMessage = {
  actions: [Actions.updateProps, Actions.showToast, Actions.updateContext],
  newProps: {
    type: "comboBox",
    id: "country-select",
    options: [
      { value: "us", label: "United States" },
      { value: "uk", label: "United Kingdom" }
    ],
    value: "us"
  },
  toastProps: [{
    type: ToastType.error,
    title: "Please complete all required fields"
  }],
  contextProps: [{
    name: "state-select",
    props: {
      type: "comboBox",
      options: [
        { value: "ca", label: "California" },
        { value: "ny", label: "New York" }
      ],
      isDisabled: false
    }
  }]
};

Properties

Property	Type	Description
actions	Actions[]	Defines a collection of events that will be processed on the portal side. The specified actions will be performed depending on the set of values.
newProps	IComboBox | IButton | ICheckbox | IInput | ITextArea | IToggleButton	Defines the properties that update the state of the items which interact with the users. This parameter is used only with Actions.updateProps.
toastProps	IToast[]	Defines the properties that display a toast notification after the user actions. This parameter is used only with Actions.showToast.
contextProps	{ name: string; props: IComboBox | IButton | ICheckbox | IFrame | IImage | IInput | ILabel | ISkeleton | IText | ITextArea | IToggleButton | IBox; }[]	Defines the properties that update the state of the parent or child item after the event was executed. Contains an array of objects with: - name: Defines the item name - props: Defines the new properties for the parent or child item
createDialogProps	ICreateDialog	Defines the properties that display the default dialog box for creating a file/folder managed by the plugin. This parameter is used only with Actions.showCreateDialogModal.
modalDialogProps	IModalDialog	Defines the properties that display the modal window. This parameter is used only with Actions.showModal.
selectorProps	TSelector	Defines the properties that display the selector. This parameter is used only with Actions.showSelector and Actions.updateSelector.
floatingOperationsButtonProps	IFloatingOperationsButton	Defines the configuration for the floating operations button that displays progress of long-running operations. Used with Actions.addFloatingOperationsButton to create a new button or Actions.updateFloatingOperationsButton to update existing one. The button appears as a floating action button in the bottom-right corner. Multiple plugins can show operations simultaneously.
floatingOperationsButtonPropsId	string	Unique identifier for the floating operations button to remove. Used only with Actions.removeFloatingOperationsButton to close a specific operations panel. The ID should match the id property of the IFloatingOperationsButton that was previously added.
postMessage	IPostMessage	Defines the properties that are used to send a message to a frame. If the frame ID is not specified or the frame with such an ID does not exist, then nothing changes. This parameter is used only with Actions.sendPostMessage.
settings	string	Defines the administrator or owner plugin settings to store, one string of at most 255 characters (see ISettingsPlugin). This parameter is used only with Actions.saveSettings. Remarks: Unlike save in the React settings client, the action does not pass the settings to the plugin class: it receives them the next time it loads.
navigatePath	string	Defines the path to navigate to. The portal starts the navigation and goes straight on to the actions listed after navigate, without waiting for the new page. This parameter is used only with Actions.navigate.
infoPanelTab	string	Defines the info panel tab to open. This parameter is used only with Actions.openInfoPanel.
mediaViewerProps	IMediaViewer	Defines the properties for the media viewer. This parameter is used only with Actions.showMediaViewer and Actions.updateMediaViewer.

---

IPostMessageCallbackMessage

A message which is returned from the postMessage callback. It is similar to IMessage but with a reduced set of available actions.

Example

Handling a postMessage callback with a toast notification

const postMessageResponse: IPostMessageCallbackMessage = {
  actions: [Actions.showToast],
  toastProps: [{
    type: ToastType.success,
    title: "Frame message processed successfully"
  }]
};

Properties

Property	Type	Description
actions	(updateContextMenuItems | updateInfoPanelItems | updateMainButtonItems | updateProfileMenuItems | updateFileItems | updateEventListenerItems | showToast | showCreateDialogModal | showModal | closeModal | showSelector | addFloatingOperationsButton | removeFloatingOperationsButton | navigate | openInfoPanel | showMediaViewer | closeMediaViewer)[]	Defines a collection of events that will be processed on the portal side. Only the following actions are available: updateContextMenuItems, updateInfoPanelItems, updateMainButtonItems, updateProfileMenuItems, updateFileItems, updateEventListenerItems, showToast, showCreateDialogModal, showModal, closeModal, showSelector, showMediaViewer, closeMediaViewer, addFloatingOperationsButton, removeFloatingOperationsButton, navigate, openInfoPanel.
toastProps	IToast[]	Defines the properties that display a toast notification after the user actions. This parameter is used only with Actions.showToast.
createDialogProps	ICreateDialog	Defines the properties that display the default dialog box for creating a file/folder managed by the plugin. This parameter is used only with Actions.showCreateDialogModal.
modalDialogProps	IModalDialog	Defines the properties that display the modal window. This parameter is used only with Actions.showModal.
selectorProps	TSelector	Defines the properties that display the selector. This parameter is used only with Actions.showSelector.
floatingOperationsButtonProps	IFloatingOperationsButton	Defines the configuration for the floating operations button that displays progress of long-running operations. Used with Actions.addFloatingOperationsButton to create a new button.
floatingOperationsButtonPropsId	string	Unique identifier for the floating operations button to remove. Used with Actions.removeFloatingOperationsButton to close a specific operations panel. The ID should match the id property of the IFloatingOperationsButton that was previously added.
navigatePath	string	Defines the path to navigate to. The portal starts the navigation and goes straight on to the actions listed after navigate, without waiting for the new page. This parameter is used only with Actions.navigate.
infoPanelTab	string	Defines the info panel tab to open. This parameter is used only with Actions.openInfoPanel.

---

TInfoPanelTab

type TInfoPanelTab = "info_members" | "info_history" | "info_details" | "info_share" | string;

Defines the info panel tab to open.

---

TReturnPostMessage

type TReturnPostMessage = 
  | Promise<IPostMessageCallbackMessage>
  | Promise<void>
  | void
  | IPostMessageCallbackMessage;

Describes a return message of a postMessage event handler.

---

TReturnMessage

type TReturnMessage = 
  | Promise<IMessage>
  | Promise<void>
  | void
  | IMessage;

Describes a return message.