Methods

After initializing document editor you will get the object that can be used to call the methods.

const docEditor = new DocsAPI.DocEditor("placeholder", config)

• createConnector - create the connector to interact with text documents, spreadsheets, presentations, and fillable forms from the outside.
• denyEditingRights - deny editing.
• destroyEditor - destroy docEditor object.
• downloadAs - download the edited file.
• insertImage - insert an image into the file.
• refreshHistory - show the document version history.
• requestClose - request to close the editor.
• setActionLink - set the link to the document which contains a bookmark.
• setFavorite - change the Favorite icon state.
• setHistoryData - send the link to the document for viewing the version history.
• setMailMergeRecipients - insert recipient data for mail merge into the file.
• setReferenceData - refresh data by a link to a file.
• setReferenceSource - change a source of the external data.
• setRequestedDocument - select a document for comparing, combining, or inserting text.
• setRequestedSpreadsheet - insert recipient data for mail merge into the file.
• setRevisedFile - select a document for comparing.
• setSharingSettings - update the information about the settings which allow to share the document with other users.
• setUsers - set a list of users to mention in the comments, grant the access rights to edit the specific sheet ranges, or set the user avatars.
• showMessage - display tooltip with the message.
• startFilling - start filling out the ready forms and lock the pdf editing.

createConnector

Create the connector to interact with text documents, spreadsheets, presentations, and fillable forms from the outside.

This parameter is available for editing only for ONLYOFFICE Developer Edition.

docEditor.createConnector()

denyEditingRights

Deny editing. This method can be called when you want to make the document editing unavailable.

docEditor.denyEditingRights(message)

destroyEditor

Destroy docEditor object. This method can be called when you want to reinit document editor with another configurations. Used since version 4.3.

docEditor.destroyEditor()

downloadAs

Download the edited file. This method can be called only when the existence of the onDownloadAs events. Document editing service asynchronously creates a document and triggers the onDownloadAs event with a link in parameter.

docEditor.downloadAs(format)

Please note that conversion from the djvu, pdf, xps formats are not available. The original format will be downloaded.

insertImage

Insert an image into the file. Starting from version 7.0, this method allows a user to insert several images. The images array is used to do it. This method must be called after the onRequestInsertImage events.

docEditor.insertImage({
  c: "add",
  images: [
    {
      fileType: "png",
      url: "https://example.com/url-to-example-image1.png",
    },
    {
      fileType: "png",
      url: "https://example.com/url-to-example-image2.png",
    },
  ],
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjIjoiYWRkIiwiaW1hZ2VzIjpbeyJmaWxlVHlwZSI6InBuZyIsInVybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWV4YW1wbGUtaW1hZ2UxLnBuZyJ9LHsiZmlsZVR5cGUiOiJwbmciLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWltYWdlMi5wbmcifV19.JfSa__qPeY3MjUgdkJDjdfJWBgvCmEdLfFzjd3WgeUA",
})

Where example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

Prior to version 7.0, this method allowed to insert only one image and had the following parameters:

docEditor.insertImage({
  c: "add",
  fileType: "png",
  url: "https://example.com/url-to-example-image.png",
})

Please note that this structure is deprecated and will not be supported by the next editors versions. Please use a new one.

refreshHistory

Show the document version history. This method must be called after the onRequestHistory events.

docEditor.refreshHistory({
  currentVersion: 2,
  history: [
    {
      created: "2010-07-06 10:13 AM",
      key: "af86C7e71Ca8",
      user: {
        id: "F89d8069ba2b",
        name: "Kate Cage",
      },
      version: 1,
    },
    {
      created: "2010-07-07 3:46 PM",
      key: "Khirz6zTPdfd7",
      user: {
        id: "78e1e841",
        name: "John Smith",
      },
      version: 2,
    },
  ],
})

If after editing and saving the document the history with the object changes and server version is returned, send the object changes in the changes parameter and the server version in the serverVersion parameter.

docEditor.refreshHistory({
  currentVersion: 2,
  history: [
    {
      created: "2010-07-06 10:13 AM",
      key: "af86C7e71Ca8",
      user: {
        id: "F89d8069ba2b",
        name: "Kate Cage",
      },
      version: 1,
    },
    {
      changes,
      created: "2010-07-07 3:46 PM",
      key: "Khirz6zTPdfd7",
      serverVersion,
      user: {
        id: "78e1e841",
        name: "John Smith",
      },
      version: 2,
    },
  ],
})

Where changes is the changes from the history object returned after saving the document.

Where serverVersion is the serverVersion from the history object returned after saving the document.

Show an error message explaining why the version history cannot be displayed:

docEditor.refreshHistory({
  error: "Exception",
})

requestClose

Request to close the editor. It is recommended to call this method before the destroyEditor method to check if there is some unsaved data in the editor or not. If the unsaved data exists, then the dialog box will be displayed to ask the user whether they want to continue editing or close the editor losing all the unsaved data. If the Close option will be chosen, then the onRequestClose event will be called.

docEditor.requestClose()

setActionLink

Set the link to the document which contains a bookmark. This method must be called after the onMakeActionLink event. The software integrator must process the ACTION_DATA received from the document editing service to set the link. The link is created by the software integrators who use ONLYOFFICE Docs in their document manager.

docEditor.setActionLink(link)

setFavorite

Change the Favorite icon state. This method must be called after the onMetaChange event.

docEditor.setFavorite(favorite)

setHistoryData

Send the link to the document for viewing the version history. This method must be called after the onRequestHistoryData events.

docEditor.setHistoryData({
  fileType: "docx",
  key: "Khirz6zTPdfd7",
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3IiwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tZXhhbXBsZS1kb2N1bWVudC5kb2N4IiwidmVyc2lvbiI6Mn0.iRcdHve235L5K1e29SmUBkuHcxb63WHRko51WMJlmS0",
  url: "https://example.com/url-to-example-document.docx",
  version: 2,
})

Where example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

If after editing and saving the document the changesurl link to the file with changes data is returned, download the file by this link and send the file URL in the changesUrl parameter. The absolute URL address of the document previous version must be sent in the previous.url parameter.

docEditor.setHistoryData({
  changesUrl: "https://example.com/url-to-changes.zip",
  fileType: "docx",
  key: "Khirz6zTPdfd7",
  previous: {
    fileType: "docx",
    key: "af86C7e71Ca8",
    url: "https://example.com/url-to-the-previous-version-of-the-document.docx",
  },
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaGFuZ2VzVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tY2hhbmdlcy56aXAiLCJmaWxlVHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3IiwicHJldmlvdXMiOnsiZmlsZVR5cGUiOiJkb2N4Iiwia2V5IjoiYWY4NkM3ZTcxQ2E4IiwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tdGhlLXByZXZpb3VzLXZlcnNpb24tb2YtdGhlLWRvY3VtZW50LmRvY3gifSwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tZXhhbXBsZS1kb2N1bWVudC5kb2N4IiwidmVyc2lvbiI6Mn0.ril3Ol3rvYne3g0dG8TdKCiwJ7-7kkYGc6-XWMvp8FU",
  url: "https://example.com/url-to-example-document.docx",
  version: 2,
})

Where example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

Send an error message explaining why the document version cannot be displayed:

docEditor.setHistoryData({
  error: "Exception",
  version: 2,
})

setMailMergeRecipients

Insert recipient data for mail merge into the file. This method must be called after the onRequestMailMergeRecipients event. Deprecated since version 7.5, please use setRequestedSpreadsheet instead.

docEditor.setMailMergeRecipients({
  fileType: "xlsx",
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6Inhsc3giLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLXJlY2lwaWVudHMueGxzeCJ9.P3TjOyX1Tv3xAVRAc8qtNb-uFLD6FH_WErag_rbI6nQ",
  url: "https://example.com/url-to-example-recipients.xlsx",
})

Where example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

setReferenceData

Refresh data by a link to a file which is specified with the referenceData, path, or link parameters. This method must be called after the onRequestReferenceData event.

This parameter is available for editing only for ONLYOFFICE Developer Edition.

Please note that this method is executed only when the user has permissions to the file from which the data is taken.

docEditor.setReferenceData({
  fileType: "xlsx",
  path: "sample.xlsx",
  referenceData: {
    fileKey: "BCFA2CED",
    instanceId: "https://example.com",
    key: "Khirz6zTPdfd7",
  },
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6Inhsc3giLCJwYXRoIjoic2FtcGxlLnhsc3giLCJyZWZlcmVuY2VEYXRhIjp7ImZpbGVLZXkiOiJCQ0ZBMkNFRCIsImluc3RhbmNlSWQiOiJodHRwczovL2V4YW1wbGUuY29tIn0sInVybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWV4YW1wbGUtZG9jdW1lbnQueGxzeCJ9.UXosmM-E_Cu9j9QGSlcj9FEoSu5m-zCS4b6FxO_2k7w",
  url: "https://example.com/url-to-example-document.xlsx",
})

Where the example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

Show an error message explaining if any error occurred:

docEditor.setReferenceData({
  error: "Exception",
})

setReferenceSource

Change a source of the external data. This method can be called after the onRequestReferenceSource event.

Please note that this method is executed only when the user has permissions to the file from which the data is taken.

docEditor.setReferenceSource({
  fileType: "xlsx",
  path: "sample.xlsx",
  referenceData: {
    fileKey: "BCFA2CED",
    instanceId: "https://example.com",
    key: "Khirz6zTPdfd7",
  },
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6Inhsc3giLCJwYXRoIjoic2FtcGxlLnhsc3giLCJyZWZlcmVuY2VEYXRhIjp7ImZpbGVLZXkiOiJCQ0ZBMkNFRCIsImluc3RhbmNlSWQiOiJodHRwczovL2V4YW1wbGUuY29tIn0sInVybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWV4YW1wbGUtZG9jdW1lbnQueGxzeCJ9.UXosmM-E_Cu9j9QGSlcj9FEoSu5m-zCS4b6FxO_2k7w",
  url: "https://example.com/url-to-example-document.xlsx",
})

Where the example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

Show an error message explaining if any error occurred:

docEditor.setReferenceSource({
  error: "Exception",
})

setRequestedDocument

Select a document for comparing, combining, or inserting text. This method must be called after the onRequestSelectDocument event.

This parameter is available only for ONLYOFFICE Enterprise Edition and ONLYOFFICE Developer Edition.

docEditor.setRequestedDocument({
  c: "compare",
  fileType: "docx",
  url: "https://example.com/url-to-example-document.docx",
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6ImRvY3giLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifQ.t8660n_GmxJIppxcwkr_mUxmXYtE8cg-jF2cTLMtuk8",
})

Where example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

setRequestedSpreadsheet

Insert recipient data for mail merge into the file. This method must be called after the onRequestSelectSpreadsheet event.

docEditor.setRequestedSpreadsheet({
  c: "mailmerge",
  fileType: "xlsx",
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6Inhsc3giLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLXJlY2lwaWVudHMueGxzeCJ9.P3TjOyX1Tv3xAVRAc8qtNb-uFLD6FH_WErag_rbI6nQ",
  url: "https://example.com/url-to-example-recipients.xlsx",
})

Where example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

setRevisedFile

Select a document for comparing. This method must be called after the onRequestCompareFile events. Deprecated since version 7.5, please use setRequestedDocument instead.

This parameter is available only for ONLYOFFICE Enterprise Edition and ONLYOFFICE Developer Edition.

docEditor.setRevisedFile({
  fileType: "docx",
  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6ImRvY3giLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifQ.t8660n_GmxJIppxcwkr_mUxmXYtE8cg-jF2cTLMtuk8",
  url: "https://example.com/url-to-example-document.docx",
})

Where example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

setSharingSettings

Update the information about the settings which allow to share the document with other users. This method can be called after the onRequestSharingSettings events.

docEditor.setSharingSettings({
  sharingSettings: [
    {
      permissions: "Full Access",
      user: "John Smith",
    },
    {
      isLink: true,
      permissions: "Read Only",
      user: "External link",
    },
  ],
})

setUsers

Set a list of users to mention in the comments, grant the access rights to edit the specific sheet ranges, or set the user avatars. This method must be called after the onRequestUsers events.

docEditor.setUsers({
  c: "protect",
  users: [
    {
      email: "john@example.com",
      id: "78e1e841",
      image: "https://example.com/url-to-user-avatar1.png",
      name: "John Smith",
    },
    {
      email: "kate@example.com",
      id: "F89d8069ba2b",
      image: "https://example.com/url-to-user-avatar2.png",
      name: "Kate Cage",
    },
  ],
})

Where example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.

Please note that the request to the user's avatar is sent without authorization because the avatar URL is inserted into the HTML of the editor frame. Moreover, the CORS problem may occur. In this case, use the avatar in the base64 format. For example, "data:image/png,base64,*****".

Please note that if you are subscribed to the onRequestUsers event and send an avatar using the setUsers method, the user.image field in the initialization config is not required. We especially don't recommend to specify this parameter if the avatar is sent in the base64 format and the initialization config is signed with JWT. In this case, the token will be too long.

showMessage

Display a tooltip with a message. This method can be called only after the onAppReady events.

docEditor.showMessage(message)

Please note that displaying a tooltip with a message is not supported in the embedded platform type.

startFilling

Start filling out the ready forms and lock the pdf editing (only pdf viewing becomes available). This method can be called only after the onRequestStartFilling event.

docEditor.startFilling()