Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Extending the ONLYOFFICE Online Editors Functionality With Plugins

DZone 's Guide to

Extending the ONLYOFFICE Online Editors Functionality With Plugins

In this article, we look at how the open source ONLYOFFICE platform can be used to create plugins.

· Web Dev Zone ·
Free Resource

ONLYOFFICE is a free and open source web-based office suite that can be easily deployed on your own server, integrated with your web application, and extended with your own plugins.

A plugin is the simplest way to add missing or additional features, like Symbol Table. Using plugins you can easily integrate document editors with any other editor, for example, to edit images. or connect any third-party service, be it online, like YouTube, or self-hosted, like Highlight Code.

In this post, we will learn how to create a simple plugin using ONLYOFFICE API, configure and make it work within ONLYOFFICE. Let’s start with some basics.

What Are ONLYOFFICE Plugins?

In ONLYOFFICE, a plugin is JSON containing the information about the main data needed to register the plugin in the editors. While working, the plugin is a regular HTML file with JavaScript code that interacts with the editor using the API.

Which ONLYOFFICE Plugins Exist?

  • Visual/non-visual (marked with the isVisual flag in the config.json): The non-visual plugins provide a button (or buttons) to apply some transformations or manipulations to the document. The visual plugins open a window or a panel for some action.

  • OLE object (marked as "initDataType": "ole" in the config.json): The OLE object is the only way to save your own information to the resulting file. The simplest example of such a plugin is YouTube or Chess.

  • Input helper: This is a new type of ONLYOFFICE plugin, which is not yet documented. This is a combination of the visual and non-visual plugin. It has its own window that appears and disappears when you type the text. Its location is tied to the cursor. An example is a combo or non-standard keyboard, or any input assistant.

  • System/non-system (marked with the isSystem flag in the config.json): The system plugin starts immediately with the editor, works in the background, and runs until it turns off. An example of a system plugin is the end-to-end encryption in the ONLYOFFICE desktop apps. The majority of the ONLYOFFICE plugins are non-system, i.e. they start with a click of the corresponding button on the toolbar.

All of the plugin samples from this post are available in the ONLYOFFICE GitHub repository.

What Is a Simple Plugin Structure?

A plugin in ONLYOFFICE is a folder with at least three files:

  • config.json - plugin configuration file.
  • index.html - plugin entry point.
  • pluginCode.js - the plugin code file itself.

This folder may contain additional files, for example icons for non-system plugins, or index_about.html for legal information about it, etc.

So let’s start by creating a new folder with a unique name to avoid naming collision with other plugins.

Writing Code for a Plugin

Next, create a .js file with code that describes what and how must be done by the plugin.

Any plugin has a  window.Asc.plugin object that uses several methods to interact with ONLYOFFICE editors.

To make the plugin work, we need to specify two methods for window.Asc.plugin: window.Asc.plugin.init and window.Asc.plugin.button.

To send the data to the editors, we use the in-built ONLYOFFICE Document Builder API features for window.Asc.plugin.callCommand.

Let’s see how it will look like for the "Hello world!" plugin:

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

It will form a paragraph with the Hello world! text and then create the document with this text using the built-in ONLYOFFICE Document Builder API.

Creating a Plugin's Main HTML File

Each plugin works in its own iframe. The editor connects to the index.html file that's specified in the config.json.

Let’s see the structure of the simple plugin main HTML file:

<!DOCTYPE html>
 <html>
 <head>
     <meta charset="UTF-8" />
     <title>Hello world</title>
     <script type="text/javascript" src="../pluginBase.js"></script>
     <script type="text/javascript" src="helloworld.js"></script>
 </head>
 <body>
 </body>
 </html>


In the <head>...</head> section we will specify the plugin title and the links to all the scripts and stylesheets necessary to make it work correctly.

Besides, we need to include the link to the pluginBase.js file that contains the base plugin method work.

The body section can contain the placeholders within the <div>...</div> tags with the plugin components whose behavior is described in the pluginCode.js.

Creating a Plugin Configuration File

Next, we are going to create the config.json file with the data needed to register our plugin in the editors.

First, we need to specify the plugin information: its name, identifier/guid, and URL.

{
     "name"       : "hello world",
     "guid"       : "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",
     "baseUrl"    : "",

The plugin "name" will be displayed on the toolbar within the Plugin tab.

Then specify the following plugin parameters:

  • "description" - Plugin description.
  • "url" - Link to the plugin main HTML file.
  • "icons" - Links to the plugin icons to be displayed on the toolbar.

We need at least two icons: for common screens and with a doubled resolution for retina screens. Both icons must be placed in the created plugin folder.

Our plugin inserts a text to the document, so we need it to be active in editing mode only, then mark "isViewer" as false . If you want your plugin to be available also for the document viewer, mark it as true.

ONLYOFFICE contains three editors for text documents, spreadsheets, and presentations. Then we need to specify the editors ( "EditorsSupport" ) we want our plugin to be present in - "word" , "cell" , or "slide" .

Our plugin is non-visual, as it provides a simple button. Then mark "isVisual" as false . If you create a visual plugin, you will need to specify two more parameters:

"isModal"             : true,
"isInsideMode"        : false,

The first one allows specifying if the plugin has its own separate modal window or not. If you want your plugin to be displayed on the editor panel instead, mark the second one - "isInsideMode" - as true.

Let’s see how our plugin config will look like:

{
     "name"       : "hello world",
     "guid"       : "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",
     "baseUrl"    : "",
     "variations" : [
         {
             "description"         : "hello world",
             "url"                 : "index.html",
             "icons"               : ["icon.png", "icon@2x.png"],
             "isViewer"            : false,
             "EditorsSupport"      : ["word"],
             "isVisual"            : false,


         }

     ]
 }

There are even more configuration parameters that you can find in ONLYOFFICE API documentation.

Localizing Your Plugin

As we have a multi-language platform, we need our plugin to be translated into different languages. To do that, we will add "nameLocale" to the config.json file to translate the plugin name:

{
     "name": "Hello world",
     "nameLocale": {
         "fr": "Bonjour le monde !",
         "de": "Hallo Welt"
     },

And "descriptionLocale" for plugin description:

"variations": [
         {
             "description": "Hello world",
             "descriptionLocale": {
                 "fr": "Bonjour le monde",
                 "de": "Hallo Welt"
             },
             "url": "index.html",

Creating an About Plugin Page

To let other users know that this plugin is created by us, we can create an About page. To do this, we need an HTML file with all the information about our plugin and the second variation in our config.json file.

It will be a visual plugin that opens a separate modal window with one OK button. The window size is specified in pixels.

{
             "description"         : "About",
             "url"                 : "index_about.html",
             "icons"               : ["icon.png", "icon@2x.png"],
             "isViewer"            : false,
             "EditorsSupport"      : ["word"],
             "isVisual"            : true,
             "isModal"             : true,
             "buttons"         : [
                 {
                     "text": "Ok",
                     "primary": true
                 }
             ],


             "size" : [392, 147]
         }

As a result, our config.json file will look like:

{
     "name": "Hello world",
     "nameLocale": {
         "fr": "Bonjour le monde !",
         "de": "Hallo Welt"
 },
     "guid"       : "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",
     "baseUrl"    : "",
     "variations": [
         {
             "description": "Hello world",
             "descriptionLocale": {
                 "fr": "Bonjour le monde",
                 "de": "Hallo Welt"
             },
             "url": "index.html",
             "icons"               : ["icon.png", "icon@2x.png"],
             "isViewer"            : false,
             "EditorsSupport"      : ["word"],
             "isVisual"            : false,

         },
         {
             "description"         : "About",
             "url"                 : "index_about.html",
             "icons"               : ["icon.png", "icon@2x.png"],
             "isViewer"            : false,
             "EditorsSupport"      : ["word"],
             "isVisual"            : true,
             "isModal"             : true,
             "buttons"         : [
                 {
                     "text": "Ok",
                     "primary": true
                 }
             ],


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

Adding Your Plugin to ONLYOFFICE

Finally, we need to add our plugin to the editor. The plugin installation process depends on the solution we want to add our plugin.

  • For server solutionsJust add the corresponding line to the config — the plugin will automatically appear for all the portal users.

  • For desktop appsArchive your plugin folder, change its extension to .plugin, go to the Plugins tab, click Manage Plugins >> Add plugin, browse for the .plugin file to upload it to the app.

  • For cloud serviceNow we are preparing a marketplace for customers’ plugins that will be added after moderation. But since there is no marketplace yet, plugins can be added via an extension in the browser. Currently, it works for Chrome users only. You can find the chrome_extension_example folder on GitHub to learn how to transform an ONLYOFFICE plugin into a Chrome extension.

That is all. Build your own plugin connecting your own service or adding some additional features and share it with ONLYOFFICE users.

Topics:
web dev ,open source ,api ,tutorial for beginners ,javascript ,plugins

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}