Skip to main content

ONLYOFFICE Apps Samples: Approval Workflows, Sidebar Pages, and Six Ready-to-Use Plugins

If you build on top of ONLYOFFICE Apps, these eight samples show two complete extension patterns and six plugins you can learn from.

Updated 5 min readMarkdown
ONLYOFFICE Apps Samples: Approval Workflows, Sidebar Pages, and Six Ready-to-Use Plugins

If you build on top of ONLYOFFICE Apps, the eight new samples show two complete extension patterns and six plugins you can learn from.

The samples split into three groups:

  • A document approval workflow built with the Embed SDK
  • An article navigation plugin that adds React pages to the sidebar (Plugins SDK)
  • Six ready-to-use plugins: Book reader, CodeMirror, Convert to markdown, Image editor, URL and ZIP archives

Let's dig in.

What the Samples Do

Document approval workflow. An author submits a document. The sample creates a custom room tagged Pending review and gives a reviewer Review access. Approving switches the reviewer to Read access and the tag to Approved; requesting changes swaps the tag to Changes requested.

Article navigation plugin. Two sidebar entries, Sample files (Files section, all user types) and Sample settings (Settings section, owners and full admins), each open a full portal page rendered from a React component.

Ready-to-use plugins. Finished plugins for reading e-books, editing code, converting documents to Markdown, editing images, storing links and working with ZIP archives.

How It Works

Rooms, Access Levels and Tags as a State Machine

The approval sample needs no workflow engine. The room's tag holds the status and the reviewer's access level enforces it. The SDK embeds ONLYOFFICE Apps with DocSpace.SDK.initManager(config); room and tag operations use createRoom(), createFile(), createTag(), addTagsToRoom() and removeTagsFromRoom(); access changes go through PUT /api/2.0/files/rooms/{roomId}/share.

const CUSTOM_ROOM = 5
const REVIEW_ACCESS = 5
const READ_ACCESS = 2

The submission step creates the room, adds the document and sets the first status:

async function createApprovalRequest() {
  const title = document.getElementById("documentTitle").value
  if (!title) return alert("Please enter a document title")
  const button = document.getElementById("createRequestBtn")
  button.disabled = true

  const room = await docSpace.createRoom(`Approval: ${title}`, CUSTOM_ROOM)
  if (!room?.id) {
    button.disabled = false
    return alert(`Error creating room: ${room?.message ?? "unknown error"}`)
  }
  roomId = room.id

  try {
    const file = await docSpace.createFile(roomId, `${title}.docx`, "{PUBLIC_DOCX_ID}")
    // A portal without API_ERROR support resolves errors instead of rejecting
    if (!file?.id) throw new Error(file?.message ?? "unknown error")
    await docSpace.createTag("Pending review")
    await docSpace.addTagsToRoom(roomId, ["Pending review"])
  } catch (error) {
    console.error(error)
    button.disabled = false
    return alert(`Error preparing the room: ${error.message}`)
  }

  document.getElementById("createStep").classList.add("hidden")
  document.getElementById("reviewerStep").classList.remove("hidden")
}

Why this matters: you can model review and sign-off flows with features ONLYOFFICE Apps already has, and the decision buttons are disabled on click so two conflicting tags can't be applied.

The room must be a custom room (type 5); collaboration rooms (type 2) reject Review access with HTTP 403. Only admins and room admins can create tags.

The plugin implements IPlugin and IArticleNavigationPlugin and registers IArticleNavigationItem objects in onLoadCallback. Each item declares where it appears and who sees it:

import { Section, UserRole, type IArticleNavigationItem } from "@onlyoffice/docspace-plugin-sdk";

const filesItem: IArticleNavigationItem = {
  key: "article-navigation-sample-files",
  label: "Sample files",
  icon: "plugin-icon.svg",
  component: FilesPage,
  appears: [Section.Files],
};

const settingsItem: IArticleNavigationItem = {
  key: "article-navigation-sample-settings",
  label: "Sample settings",
  icon: "plugin-icon.svg",
  component: SettingsPage,
  appears: [Section.Settings],
  usersTypes: [UserRole.owner, UserRole.fullAdmin],
};

The pages run inside the portal's React tree. useCurrentUser returns the profile, usePluginActions exposes showToast, and the portal draws the toast.

Why this matters: your plugin UI looks native because it inherits the portal theme, but only if you import @onlyoffice/apps-ui-kit from the package root. Subpath imports such as @onlyoffice/apps-ui-kit/components/button fail to load.

Requires ONLYOFFICE Apps 4.0.0 or later.

Ready-to-Use Plugins as Interface Recipes

Each ready-to-use plugin combines a few Plugins SDK interfaces on top of IPlugin:

Plugin Interfaces
Book reader IContextMenuPlugin, IFilePlugin
CodeMirror IApiPlugin, ISettingsPlugin, IContextMenuPlugin, IMainButtonPlugin, IFilePlugin
Convert to markdown IApiPlugin, IContextMenuPlugin
Image editor IApiPlugin, IContextMenuPlugin
URL IApiPlugin, ISettingsPlugin, IMainButtonPlugin, IContextMenuPlugin, IFilePlugin
ZIP archives IApiPlugin, IContextMenuPlugin, IFilePlugin

Why this matters: if your plugin needs a new file type plus a menu action, the URL and ZIP archives sources show exactly that combination.

https://github.com/ONLYOFFICE/docspace-plugins

Running the Samples

  1. The ready-to-use plugins are enabled by default in ONLYOFFICE Apps cloud. Elsewhere, enable them as system plugins.
  2. For the approval workflow, serve the HTML from a web server, add its root URL in Developer Tools, and sign in as an admin or room admin. Keep credentials out of client code in production.
  3. For the article navigation plugin, run npm run build and upload dist/plugin.zip in Settings → Integration → Plugins.

Where to Take It Next

  • Add more states to the approval flow, such as a second reviewer, by adding tags and access changes.
  • Turn a sidebar page into a settings screen for your integration.
  • Fork Convert to markdown to export to another text format.
  • Use the CodeMirror settings block as a template for plugin settings.

To get started, check the Plugins SDK and the Embed SDK.

About the author

  • Tech content creator at ONLYOFFICE. Author of how-to articles, contributor on GitHub, switched from outdated Windows to Kubuntu, have been working with open-source office software since 2017.

No comments yet. Be the first to comment.