How to add a new plugin as a tab to ONLYOFFICE Docs

With the release of ONLYOFFICE Docs 8.1, we’ve introduced a wide range of new features designed to enhance versatility and streamline the user experience. Among these improvements is the ability to display plugins in a separate tab. In this blog post, we’ll walk you through the steps to make the most of this new feature.

What it’s all about

This feature allows you to create a dedicated tab in the toolbar for a specific plugin.

This tab can contain additional functionality for your plugin, making it easily accessible.

Implementation

To activate this feature in your plugin you will need to make changes to two files:

config.json – In the config.json file, you’ll need to subscribe to the onToolbarMenuClick event by adding the events parameter to your plugin configuration.

  "events"              : ["onToolbarMenuClick"]

code.js – In the code.js file, you’ll need to use the AddToolbarMenuItem method, which enables the creation of a separate tab and displays its items.

this.executeMethod("AddToolbarMenuItem", [getToolbarItems()]);

Plugin as tab example

Let’s take a closer look at these changes. For demonstration purposes, we’ll create a new plugin that inserts several objects into a text document, with the insertion options managed through the toolbar menu. The plugin example can be found at this GitHub repository.

Modifying the config.json file

To register the events that trigger the creation of an additional tab, we add the  onToolbarMenuClick to the events parameter.

The entire config.json file:

{
    "name"       : "Plugin as tab",
    "guid"       : "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",
    "baseUrl"    : "",
    "variations" : [
        {
            "description"         : "Example of displaying a plugin in a separate tab",
            "url"                 : "index.html",
            "icons"               : ["resources/img/icon.png", "resources/img/icon@2x.png"],
            "isViewer"            : false,
            "EditorsSupport"      : ["word"],
            "isVisual"            : false,
            "isModal"             : false,
            "isInsideMode"        : false,
            "initDataType"        : "none",
            "initData"            : "",
            "isUpdateOleOnResize" : true,
            "buttons"             : [],
            "events"              : ["onToolbarMenuClick"]
        }
    ],
    "store": {
                "background": {
                    "light": "radial-gradient(circle, #B5BCC3 0%, #737D87 100%)",
                    "dark": "radial-gradient(circle, #B5BCC3 0%, #737D87 100%)"
                },
                "icons": {
                    "light": "resources/store/icons",
                    "dark": "resources/store/icons"
                },
                "categories": ["specAbilities", "work"]
            }
}

Modifying the code.js file

Initializing the plugin and adding toolbar items

To initialize the plugin we use the window.Asc.plugin.init method. This method is the entry point of the plugin and is automatically called when the plugin is loaded.

 window.Asc.plugin.init = function () {
      this.executeMethod("AddToolbarMenuItem", [getToolbarItems()]);// the rest of the plugin code
  }

executeMethod(“AddToolbarMenuItem”): This method adds the custom tab and its items to the toolbar. It takes the configuration returned by the getToolbarItems function:

  function getToolbarItems() {
        console.log()
        let items = {
          guid: window.Asc.plugin.info.guid,
          tabs: [{
            id: "tab_1",
            text: "Insert options",
            items: [
              {
                id: "insertText",
                type: "button",
                text: "Insert text",
                hint: "insert text into the document",
                icons: "resources/buttons/icon_txt.png", 
                lockInViewMode: true,
                enableToggle: false,
                separator: false
              },
              {
                id: "insertOleObject",
                type: "button",
                text: "Insert OLE Object",
                hint: "Insert an OLE object into the document",
                icons: "resources/buttons/icon_ole.png", 
                lockInViewMode: true,
                enableToggle: false,
                separator: false
              },
              {
                id: "insertImage",
                type: "button",
                text: "Insert image",
                hint: "Insert an image into the document",
                icons: "resources/buttons/icon_img.png", 
                lockInViewMode: true,
                enableToggle: false,
                separator: false
              }
            ]
          }]
        };
  
        return items;
      }
    };

This function returns the configuration object that defines the tab and its buttons:

• guid: Unique identifier for the plugin.
• tabs: Array of tab objects, each containing an ID, text label, and an array of items.
• items: Array of button configurations, where each button has properties like id, type, text, hint, icons, etc.

Handling toolbar items click events

Each toolbar button in our custom tab triggers an event when clicked. We need to handle these events to execute the corresponding actions. This is done using the attachToolbarMenuClickEvent method.

When the Insert text button is clicked, we execute a command to insert a new paragraph with formatted text:

 this.attachToolbarMenuClickEvent("insertText", function (data) {
        this.callCommand(function () {
          var oDocument = Api.GetDocument();
  
          // Create a new paragraph
          var oParagraph = Api.CreateParagraph();
  
          // Add text to the paragraph
          oParagraph.AddText("ONLYOFFICE Docs 8.1");
  
          // Style the text as a title
          oParagraph.SetBold(true);              // Make the text bold
          oParagraph.SetFontSize(24);            // Increase the font size
          oParagraph.SetJc("center");         // Align text to the center
  
          // Insert the paragraph at the beginning of the document
          oDocument.InsertContent([oParagraph],0);
        });
      });

For the Insert OLE Object button, an OLE object (e.g. a youtube video) is inserted into the document:

  this.attachToolbarMenuClickEvent("insertOleObject", function (data) {
        this.callCommand(function () {
          var oDocument = Api.GetDocument();
          var oOleObject = Api.CreateOleObject("data:image/jpeg;base64,<Base64ImageCode>", 130 * 36000, 90 * 36000, "https://www.youtube.com/watch?v=oYlRfQ2zhaQ", "asc.{38E022EA-AD92-45FC-B22B-49DF39746DB4}");
          var oParagraph = oDocument.GetElement(0);
          oParagraph.AddDrawing(oOleObject);
          oParagraph.SetJc("center");
        });
  
      });

The Insert image button allows users to insert an image:

this.attachToolbarMenuClickEvent("insertImage", function (data) {
        this.callCommand(function () {
  
          var oDocument = Api.GetDocument();
          var oParagraph = oDocument.GetElement(0);
          var oDrawing = Api.CreateImage("data:image/jpeg;base64,<Base64ImageCode>", 150 * 36000, 90 * 36000);
          oParagraph.SetJc("center");
          oParagraph.AddDrawing(oDrawing);
  
        });
      });

Let’s see this plugin in action!

We hope this article proves valuable as you integrate this innovative feature into your plugins. At ONLYOFFICE, we are committed to continuously enhancing the user experience by introducing new features and improvements.

We encourage developers to take advantage of these new capabilities by creating innovative plugins that leverage them. We are always open to collaboration and discussion, so feel free to share your plugins with us. Together, we can continue to make ONLYOFFICE an even more powerful tool. Best of luck in your exploratory endeavors!