Creating a main button plugin
This guide walks you through creating a basic plugin for DocSpace that adds a button to the main toolbar and logs an action when clicked.
Before you start
Make sure you have a DocSpace server running, and install DocSpace Plugins SDK globally:
npm i -g @onlyoffice/docspace-plugin-sdk
Step 1: Create a plugin
-
Initialize your plugin using the CLI:
npx create-docspace-plugin
-
Fill out basic metadata: plugin name, version, author, description, logo, license, homepage.
-
Select the required scopes from the list of available options. Use the arrow keys to highlight
Main button
, pressSpace
to select it, then pressEnter
to confirm and generate the plugin template.
Step 2: Confirm plugin configuration
Ensure package.json
includes all the necessary fields. Most importantly, make sure it contains:
{
"scopes": ["MainButton"]
}
Also verify that the scripts/createZip.js
file is present. This script will:
- compile your plugin;
- package everything into
dist/plugin.zip
.
Step 3: Review and extend plugin code
By default, the plugin template includes a basic implementation in the src/index.ts
file. Here's an example of a main button plugin:
import {
IPlugin, PluginStatus, IMainButtonPlugin, IMainButtonItem
} from '@onlyoffice/docspace-plugin-sdk'
class Test implements IPlugin, IMainButtonPlugin {
status: PluginStatus = PluginStatus.active;
mainButtonItems: Map<string, IMainButtonItem> = new Map();
onLoadCallback = async () => {};
updateStatus = (status: PluginStatus) => { this.status = status };
getStatus = () => this.status;
setOnLoadCallback = (callback: () => Promise<void>) => { this.onLoadCallback = callback };
addMainButtonItem = (item: IMainButtonItem) => { this.mainButtonItems.set(item.key, item) };
getMainButtonItems = () => this.mainButtonItems;
updateMainButtonItem = (item: IMainButtonItem) => { this.mainButtonItems.set(item.key, item) };
}
const plugin = new Test();
declare global {
interface Window {
Plugins: any;
}
}
window.Plugins.Test = plugin || {};
export default plugin;
Step 4: Add a main button item
Create a main button item and append it to the end of the script:
const plugin = new Test();
// Add this after generating the plugin
const createItem: IMainButtonItem = {
key: "test-main-button-item_create",
label: "Create new",
icon: "icon.svg",
onClick: (id: number) => {
// Optional: use id to take action based on room/task/etc.
},
};
const mainButtonItem: IMainButtonItem = {
key: "test-main-button-item_create",
label: "Do something",
icon: "icon.svg",
items: [createItem], // Optional nested submenu
onClick: () => {
console.log("Main Button works!");
},
};
plugin.addMainButtonItem(mainButtonItem);
declare global {
interface Window {
Plugins: any;
}
}
Step 5: Build the plugin
From the root of your plugin, run the following command:
npm run build
This compiles src/index.ts
to dist/plugin.js
and runs scripts/createZip.js
to bundle everything into dist/plugin.zip
Step 6: Upload to DocSpace
- Log in as an administrator.
- Navigate to: Admin Panel → Integration → Plugins.
- Click Upload, and select the generated
dist/plugin.zip
. - Enable the plugin toggle if it is not already active.
Step 7: Test it
- Go to any room.
- Click Actions → More in the top toolbar.
- Look for your button titled
"Do something"
. - Click it - it should log
"Main Button works!"
in the browser console.