Debugging ONLYOFFICE plugins: practical guide

Developing and debugging ONLYOFFICE plugins can be challenging, but with the right tools and techniques, the process can be made much easier. This guide will walk you through the steps needed to effectively debug plugins in different environments.

About ONLYOFFICE plugins

ONLYOFFICE allows you to extend the functionality of its editors through plugins. These plugins are HTML pages that are embedded in the editor and use an API to interact with it. Understanding the plugin structure and debugging methods is key to successful development.

Plugin structure

A typical ONLYOFFICE plugin consists of the following files:

• config.json : A configuration file that defines basic information about the plugin.
• index.html: The main HTML page of the plugin.
• scripts: A directory containing the JavaScript files required for the plugin’s functionality.

A detailed structure and examples are available here.

Debugging plugins in web editors

To debug plugins in the web version of the ONLYOFFICE editor, follow these steps:

• Add the debugger command to your script.

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• Press F12 to open the console in your browser.
• In the ONLYOFFICE editor, go to the Plugins tab and run your plugin.

Note: The debugger command will only work if the developer tools are open; otherwise, it will be ignored. You can read more about that, on this page.

Debugging plugins in desktop editors

To debug plugins in the desktop version of the ONLYOFFICE editor, use the following approach:

• Run the editor with the –ascdesktop-support-debug-info flag.

• This flag enables the display of additional information useful for debugging.
• Similar to the web editors, insert debugger; at the desired location in your code.

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• Press F1 to open the console and run the plugin.

After starting the editor with the specified flag, open the plugin and trace the code execution.

Detailed instructions for different operating systems are available here.

Managing scopes

When developing an ONLYOFFICE plugin, it’s important to understand how to pass data between your plugin’s user interface (the HTML page)  and the editor’s execution environment where the Document Builder API commands are run. These are different context or scopes.

A common source of bugs is improper handling of data between these scopes. ONLYOFFICE  provides the Asc.scope object to facilitate this. You can attach variables to Asc.scope in your plugin’s main script, and they will be accessible within the function passed to this.callCommand().

Here is an example of how to pass a text variable to your plugin to the editor:

(function (window, undefined) {
    window.Asc.plugin.init = function () {
    // In your main script (e.g., scripts/plugin.js)
    let text = "Hello from the plugin!";
    Asc.scope.dataForEditor = text; // Export variable to the shared plugin scope
    // In the command executed in the editor's scope
    this.callCommand(function () {
         debugger;
         let oDocument = Api.GetDocument();
         let Paragraph = Api.CreateParagraph();
         oParagraph.AddText(Asc.scope.dataForEditor);// Access the variable via Asc.scope
         oDocument.InsertContent([oParagraph]);
    }, true);
  };
})(window, undefined);

Properly using Asc.scope ensures that data is passed correctly between different contexts,which is critical for building complex plugins.

Common issues and troubleshooting

While debugging you may encounter several common issues. Here are some of the most frequent problems and their solutions:

Debugger statement is not working

The debugger; statement is ignored and execution doesn’t pause.

• Make sure the browser’s developer tools (F12) are open before running the plugin.
• The debugger; statement only works when DevTools are active.

Plugin not loading or not visible

• Check that your config.json file is properly formatted (valid JSON).
• Verify that all required fields in config.json are present (name, guid, baseUrl).
• Check the browser console for any loading errors.
• Ensure the plugin is properly installed in the ONLYOFFICE plugins tab.
• Manual installation with zipped  .plugin file or Asc.editor.installDeveloperPlugin() method.

Cors (cross-origin resource sharing) errors

• Install ONLYOFFICE Docs.
• For web editors in ONLYOFFICE Docs, make sure you run http-server inside of your plugin folder.
• Or adjust path to your config.json file in installDeveloperPlugin().

Asc.editor.installDeveloperPlugin("https://<documentserver>:<port>/<folder-name>/config.json")

Files changed, old code is still running – Web Editors

• If you changed local files of your plugin, you’ll need to refresh your page and cache.
• Right click on the refresh button of your browser and select “Empty Cache and Hard Reload”, then  run your plugin again.

Effective debugging is crucial for developing stable and functional ONLYOFFICE plugins. By using the techniques and tools mentioned, you can quickly identify and resolve issues in your code, thereby improving the quality and performance of your plugins.

We welcome your questions, suggestions, and plugin ideas. If you’d like to share your work with us, please don’t hesitate to get in touch. We’re open to collaboration and happy to connect.