Getting started

Let's see how to build the simplest Hello world plugin, which inserts the Hello World! phrase when you press the button.

Building a plugin

Create a plugin folder. Follow the plugin structure described here. The plugin folder must contain three files required for the plugin to work: config.json, index.html, pluginCode.js:

Structure

config.json

{
  "name": "hello world",
  "guid": "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",
  "baseUrl": "",
  "variations": [
    {
      "description": "hello world",
      "url": "index.html",
      "icons": ["resources/img/icon.png", "resources/img/icon@2x.png"],
      "isViewer": false,
      "EditorsSupport": ["word"],
      "isVisual": false,
      "isModal": true,
      "isInsideMode": false,
      "initDataType": "none",
      "initData": "",
      "isUpdateOleOnResize": true,
      "buttons": []
    },
    {
      "description": "About",
      "url": "index_about.html",
      "icons": ["resources/img/icon.png", "resources/img/icon@2x.png"],
      "isViewer": false,
      "EditorsSupport": ["word"],
      "isVisual": true,
      "isModal": true,
      "isInsideMode": false,
      "initDataType": "none",
      "initData": "",
      "isUpdateOleOnResize": true,
      "buttons": [
        {
          "text": "Ok",
          "primary": true
        }
      ],

      "size": [392, 147]
    }
  ]
}

index.html

<!DOCTYPE html>
<html>
<head>
 <meta charset="UTF-8" />
 <title>Hello world</title>
 <script type="text/javascript" src="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins.js"></script>
 <script type="text/javascript" src="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins-ui.js"></script>
 <link rel="stylesheet" href="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins.css">
 <script type="text/javascript" src="scripts/helloworld.js"></script>
</head>
<body>
</body>
</html>

pluginCode.js

// Example insert text into editors (different implementations)
((window) => {
  const text = "Hello world!"
  window.Asc.plugin.init = () => {
    const variant = 2

    switch (variant) {
    case 0:
      // serialize command as text
      let sScript = "var oDocument = Api.GetDocument();"
      sScript += "oParagraph = Api.CreateParagraph();"
      sScript += "oParagraph.AddText('Hello world!');"
      sScript += "oDocument.InsertContent([oParagraph]);"
      this.info.recalculate = true
      this.executeCommand("close", sScript)
      break
    case 1:
      // call command without external variables
      this.callCommand(() => {
        const oDocument = Api.GetDocument()
        const oParagraph = Api.CreateParagraph()
        oParagraph.AddText("Hello world!")
        oDocument.InsertContent([oParagraph])
      }, true)
      break
    case 2:
      // call command with external variables
      Asc.scope.text = text // export variable to plugin scope
      this.callCommand(() => {
        const oDocument = Api.GetDocument()
        const oParagraph = Api.CreateParagraph()
        oParagraph.AddText(Asc.scope.text) // or oParagraph.AddText(scope.text);
        oDocument.InsertContent([oParagraph])
      }, true)
      break
    default:
      break
    }
  }

  window.Asc.plugin.button = (id) => {}
})(window)

Use plugin methods and events while writing the plugin code. For example, in the Hello world plugin, we use the init and button events, and the callCommand and executeMethod methods.

Read the plugin customization section to find out how the plugin can be displayed in the editor: as context menu items, toolbar buttons, windows, left or right panels, input helpers. Choose the option that is suitable for your plugin and customize it following our instructions.

Add the ONLYOFFICE style sheet to the index.html file to adjust your plugin to the ONLYOFFICE editor style:

<link rel="stylesheet" href="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins.css">

Localize your plugin if needed.
Create an informative About window for your plugin. Add a short description and the plugin version, the company developer name and link to its website. Follow the instructions here to create an About variation in the config.json file.
Don't forget to create the index_about.html file for the About window.

Connecting a plugin to the editors

To desktop editors

Pack all the plugin files within the plugin folder into a zip archive and change its extension to .plugin (all the plugin files and subfolders must be at the archive root).
Install a plugin through the Plugin Manager.
The plugin will appear in the sdkjs-plugins directory. The path to the folder depends on the operating system you use:
- For Linux - home/<username>/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/
- For Windows - C:\Users\<username>\AppData\Local\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\
- For macOS - Users/<username>/Library/Application Support/asc.onlyoffice.ONLYOFFICE/sdkjs-plugins/
A plugin GUID will be used as the folder name. For example, {07FD8DFA-DFE0-4089-AL24-0730933CC80A}.
You can edit the plugin and reload it to see the changes.
To debug the plugin in the desktop editors, follow the instructions here.

To web editors

Start distributing a folder. To do this, open the created folder and run the following commands:
```
npm install http-server -g
http-server -p <port> --cors
```
where port is the port number with ONLYOFFICE Docs installed.
CORS requests are needed so that plugin files can be loaded from any server.
Open the developer console in any ONLYOFFICE web editor, go to the Console tab, choose the frameEditor from the drop-down list, and run the following command:
```
Asc.editor.installDeveloperPlugin("https://<documentserver>:<port>/config.json")
```
where documentserver is the name of the server, and port is the port number with the ONLYOFFICE Docs installed.
Please note that this is important to open your plugin in the Plugin Manager and check how it looks like in the My Plugins tab both in the light and dark themes. Improve the plugin display if necessary.
The plugin will be displayed within the Plugins tab. You can edit the plugin and reload it to see the changes.
To debug the plugin in the web editors, follow the instructions here.

Get Help

If you have any questions about ONLYOFFICE Docs, try the FAQ section first.
You can request a feature or report a bug by posting an issue on GitHub.
You can also ask our developers on ONLYOFFICE forum (registration required).