PluginActions

Portal-side actions available to a React plugin component. Returned by usePluginActions.

Example

function MyPanel() {
  const { showToast, showModal, closeModal } = usePluginActions();

  return (
    <button onClick={() => showToast({ type: ToastType.success, title: "Done!" })}>
      Notify
    </button>
  );
}

Methods

showToast()

showToast(props: IToast): void;

Show a toast in the corner of the portal. It fades on its own.

Parameters

Parameter	Type
props	IToast

Returns

void

Example

showToast({ type: ToastType.success, title: "File uploaded" });

showModal()

showModal(props: IModalDialog): void;

Open a modal dialog. One at a time — a second call replaces the open one.

Parameters

Parameter	Type
props	IModalDialog

Returns

void

Example

showModal({ dialogHeader: "File details", dialogBodyComponent: Details });

closeModal()

closeModal(): void;

Close the open modal dialog. A no-op when none is open.

Returns

void

Example

<button onClick={closeModal}>Cancel</button>

showSelector()

showSelector(props: TSelector): void;

Open a selector for picking files, folders, rooms, users or groups.

Parameters

Parameter	Type
props	TSelector

Returns

void

Example

showSelector({
  type: SelectorType.Files,
  props: {
    submitButtonLabel: "Attach",
    onSubmit: ({ selectedIds }) => ({ actions: [Actions.closeSelector] }),
  },
});

updateSelector()

updateSelector(props: TSelector): void;

Replace the props of the open selector, keeping it on screen. Use it to feed in items once they load, or to flip the submit button.

Parameters

Parameter	Type
props	TSelector

Returns

void

Example

updateSelector({ ...selector, props: { ...selector.props, isLoading: false, items } });

closeSelector()

closeSelector(): void;

Close the open selector. A no-op when none is open.

Returns

void

Example

onSubmit: ({ selectedIds }) => { save(selectedIds); closeSelector(); }

showCreateDialog()

showCreateDialog(props: ICreateDialog): void;

Open the portal's create-file dialog for a file the plugin owns: the portal draws the dialog, and the callbacks on the props do the work. Answering one of them with an IMessage carrying Actions.updateCreateDialogModal is what changes the open dialog — its title, its error text or the extension in the combo box.

Parameters

Parameter	Type	Description
props	ICreateDialog	The dialog: its title, its starting value, the extension it creates and the onSave / onChange / onSelect callbacks.

Returns

void

Example

showCreateDialog({
  isCreateDialog: true,
  title: "New report",
  startValue: "Report",
  extension: "docx",
  onSave: async (_, value) => {
    await api.post("/files/@my/file", { title: `${value}.docx` });
    return { actions: [Actions.showToast], toastProps: [{ type: ToastType.success, title: "Created" }] };
  },
});

navigate()

navigate(path: string): void;

Navigate the portal to another route, without a full page reload.

Parameters

Parameter	Type	Description
path	string	Absolute portal path, e.g. "/rooms/shared".

Returns

void

Example

navigate("/rooms/shared");

openInfoPanel()

openInfoPanel(tab?: string): void;

Open the info panel, optionally on a particular tab. Already open, it stays open and switches to the tab.

Parameters

Parameter	Type	Description
tab?	string	The tab to show: one of the portal's own ("info_details", "info_members", "info_history", "info_share") or the key of an info panel item this plugin registered. Always pass it: left out, the portal stores an invalid view, opens the panel on its first tab and the user's remembered tab is lost.

Returns

void

Example

<button onClick={() => openInfoPanel("info_details")}>Show details</button>
<button onClick={() => openInfoPanel("info_history")}>Show history</button>

showMediaViewer()

showMediaViewer(props: IMediaViewer): void;

Open the media viewer over the portal, rendering the plugin's own content.

Parameters

Parameter	Type
props	IMediaViewer

Returns

void

Example

showMediaViewer({ fileId: file.id, title: file.title, component: Preview });

updateMediaViewer()

updateMediaViewer(props: IMediaViewer): void;

Replace the props of the open media viewer, keeping it on screen.

Parameters

Parameter	Type
props	IMediaViewer

Returns

void

Example

updateMediaViewer({ fileId: nextId, title: nextTitle, component: Preview });

closeMediaViewer()

closeMediaViewer(): void;

Close the open media viewer. A no-op when none is open.

Returns

void

Example

<button onClick={closeMediaViewer}>Done</button>

addFloatingOperationsButton()

addFloatingOperationsButton(props: IFloatingOperationsButton): void;

Add a floating button that tracks long-running operations. Buttons from all plugins share one panel; id identifies this plugin's group.

Parameters

Parameter	Type
props	IFloatingOperationsButton

Returns

void

Example

addFloatingOperationsButton({
  id: "export",
  operations: [{ id: "1", label: "Exporting", operation: FloatingOperationType.Other,
    alert: false, completed: false, percent: 0 }],
});

updateFloatingOperationsButton()

updateFloatingOperationsButton(props: IFloatingOperationsButton): void;

Push new progress into an existing floating button. Call it as work advances.

Parameters

Parameter	Type
props	IFloatingOperationsButton

Returns

void

Example

updateFloatingOperationsButton({
  id: "export",
  operations: [{ id: "1", label: "Exporting", operation: FloatingOperationType.Other,
    alert: false, completed: false, percent: 60 }],
});

removeFloatingOperationsButton()

removeFloatingOperationsButton(id: string): void;

Remove the plugin's floating button and its operations from the panel.

Parameters

Parameter	Type	Description
id	string	The id the button was added with.

Returns

void

Example

removeFloatingOperationsButton("export");

updateContextMenuItems()

updateContextMenuItems(): void;

Redraw the plugin's context menu items.

Every update*Items action below works the same way: mutate the item on the plugin instance first, then call this so DocSpace re-reads the collection. They exist because item metadata — labels, icons, visibility — lives on the plugin class, outside the React tree, where setState cannot reach it.

Returns

void

Example

plugin.updateContextMenuItem({ ...item, label: "Convert (beta)" });
updateContextMenuItems();

updateInfoPanelItems()

updateInfoPanelItems(): void;

Redraw the plugin's info panel tabs.

Returns

void

Example

plugin.updateInfoPanelItem({ ...item, subMenu: { name: "Analysis (3)" } });
updateInfoPanelItems();

updateMainButtonItems()

updateMainButtonItems(): void;

Redraw the plugin's main button entries.

Returns

void

Example

plugin.updateMainButtonItem({ ...item, label: "Import from Drive" });
updateMainButtonItems();

updateProfileMenuItems()

updateProfileMenuItems(): void;

Redraw the plugin's profile menu entries.

Returns

void

Example

plugin.updateProfileMenuItem({ ...item, label: "My reports (3)" });
updateProfileMenuItems();

updateFileItems()

updateFileItems(): void;

Redraw the plugin's file items — the badges and actions shown on file rows.

Returns

void

Example

plugin.updateFileItem({ ...item, fileTypeName: "Signed" });
updateFileItems();

updateEventListenerItems()

updateEventListenerItems(): void;

Re-register the plugin's event listeners, so added or removed ones take effect.

Returns

void

Example

plugin.addEventListenerItem({ key: "on-rename", eventType: Events.RENAME, eventHandler });
updateEventListenerItems();

updateArticleButtonItems()

updateArticleButtonItems(): void;

Redraw the plugin's article button items above the sidebar DevTools section.

Returns

void

Example

plugin.updateArticleButtonItem({ ...item, component: NextButton });
updateArticleButtonItems();

updateArticleNavigationItems()

updateArticleNavigationItems(): void;

Redraw the plugin's navigation items in the sidebar, so a new label or icon becomes visible.

Returns

void

Example

plugin.updateArticleNavigationItem({ ...item, label: "Reports (3)" });
updateArticleNavigationItems();