ONLYOFFICE Docs 8.1 for developers: API updates

Along with the release of the new features in version 8.1, we updated API for the editors, Document Builder, and plugins, as well as added the Office API section. Check all the details below.

PDF forms

Starting from version 8.1, we completely switched to PDF forms. To create and edit a form, users don’t need other formats anymore. This means that the docxf format previously used for building form templates is now deprecated.

In this regard, please check the following API updates:

• documentType of the docxf and oform formats is changed to pdf;
• pdf field is added to the conversion request;
• formsubmit action is added to the WOPI discovery;
• the docs_api_config parameter is added to the form element of the WOPI host page.

Form submission

The newly added onSubmit event is called when the form is successfully submitted. It can make the form submission action more intuitive for users.

In the code sample below, once the form is successfully submitted, a message is printed to the console. For example, you can display something like a hint for users “Your form was successfully submitted”.

var onSubmit = function (event) {
    console.log("The form was submitted.");
};
var docEditor = new DocsAPI.DocEditor("placeholder", {
    "events": {
        "onSubmit": onSubmit,
        ...
    },
    ...
});

Recipient roles management

By default, the Manage Roles feature is enabled, providing you with the flexibility to assign roles and colors as needed. If you find that recipient roles and the associated role-matching colors are not essential for your forms, you have the option to disable this feature.

To do so, use the roles field added to the editorConfig.customization.features parameter. It defines if the role settings will be disabled in PDF forms or not. If the parameter is set to false, then the role manager is hidden and viewing the form on behalf of a specific role is disabled. In this case, the Manage Roles and View Form buttons on the Forms tab and a drop-down list for setting the field role in the right panel will not be displayed.

Extended Automation API

Automation API which makes it possible to interact with files form the outside features several new methods:

• addContextMenuItem – to add an item to the context menu;
• addToolbarMenuItem – to add an item to the toolbar menu;
• updateContextMenuItem – to update an item in the context menu with the specified items.

For example, if you want to update the context menu items, use the updateContextMenuItem method. Here, pass an array with new items as an argument, specifying all the necessary parameters for each item. In the code sample below, we are passing an element with the “onConvert” ID and the “Convert to Markdown or HTML” text.

var items: [
    {
        "id": "onConvert",
        "text": getMessage("Convert to Markdown or HTML")
    }
]
connector.updateContextMenuItem(items);

Please note: Automation API is included in the 30-day trial of ONLYOFFICE Docs Developer, so you can try it for free. If you are planning to use Automation API for production, you will need to obtain a license with this option included.

Customization

Use the newly added parameters to adjust the editors’ interface.

The editorConfig.customization.layout.header.editMode parameter defines if a button for switching the modes will be displayed in the header or not.

Please note: this API parameter is available for users with the extended Docs Developer license. To access this feature, please submit your request.

The visible field of the editorConfig.customization.logo parameter shows or hides the logo (image file at the top left corner of the editor header). Besides, it is now also available for the mobile editors.

Shard key for a reliable cluster

The WOPISrc query parameter introduced in the previous version is added to the requests from the browser to the server. This allows you to create several independent instances of ONLYOFFICE. Load balancing requests with WOPISrc ensure that collaborative editing works correctly: all users editing the same document are served by the same server. For WOPI, the parameter sent by the integrator is used. For Docs API, the new Shard key parameter is used.

The shardkey parameter is added to the URL QueryString when sending requests to the Document Command Service, Document Conversion Service, or Document Builder Service. The key field is used as a value. For example, ?shardkey=Khirz6zTPdfd7. If there is no key in the body, you do not have to send it (for example, in the getForgottenList command).

Further API updates for the editors

• The -10 error code (size limit exceeded) is added to the Conversion API.
• The default value of the editorConfig.customization.hideRightMenu parameter is changed to true (i.e. the right menu will be hidden on first loading).
• The editorConfig.customization.layout.toolbar.home.mailmerge field is deprecated, please use the editorConfig.customization.layout.toolbar.collaboration.mailmerge field instead (since the Mail merge button is moved to the Collaboration tab).
• The editorConfig.customization.goback.requestClose field is deprecated, please use the editorConfig.customization.close field instead.

Get the latest version of ONLYOFFICE Docs Developer:

DOWNLOAD NOW

API enhancements for plugins

Starting from version 8.1, plugins can change the toolbar: create their own tabs and fill them, add buttons to the standard tabs. To do so, use the AddToolbarMenuItem method.

var oToolbarMenuItem = {
    "id": "MeaningItem",
    "type": "button",
    "text": "Meaning",
    "hint": "Meaning",
    "icons": "resources/light/icon.png",
    "disabled": false,
    "enableToggle": false,
    "lockInViewMode": false,
    "separator": true,
    "split": true,
    "items": [
        {
            "id": "onMeaningT",
            "text": "Explain text in comment"
        },
        {
            "id": "onFixSpelling",
            "text": "Fix spelling & grammar"
        },
        {
            "id": "onMakeLonger",
            "text": "Make longer"
        },
        {
            "id": "onMakeShorter",
            "text": "Make shorter"
        }
    ]
};
var oToolbarMenuTab = {
    "id": "ChatGPT",
    "text": "AI Assistant",
    "items": [oToolbarMenuItem]
};
var oToolbarMenuMainItem = {
    "guid": "asc.{9DC93CDB-B576-4F0C-B55E-FCC9C48DD007}",
    "tabs": [oToolbarMenuTab]
};
window.Asc.plugin.executeMethod ("AddToolbarMenuItem", [[oToolbarMenuMainItem]]);

Besides, plugins can now create not only multiple windows, but also multiple left panels. The variations.menu parameter specifies where the plugin will be placed – on the right or left panel.

Among the new plugin methods you will find:

• onToolbarMenuClick
• ActivateWindow
• GetSelectedOleObjects
• GetAllComments
• and others

Check the full list of the plugin API updates.

Python Framework for Document Builder

For ONLYOFFICE Document Builder, there is now a Python Builder Framework available. It contains a collection of libraries, classes, and functions that make it much easier to quickly develop applications in Python that feature document creation abilities.

Office API

For your convenience and easier navigation, we moved the JavaScript library for working with the editors into a separate section – Office JavaScript API.

Here, we also added numerous new methods for the version 8.1, including those for:

• date forms;
• setting text properties;
• protected ranges;
• pasting/cutting ranges;
• reference styles;
• worksheet function;
• custom function;
• moving a cursor.

Check the full list of new methods.