Skip to main content

Methods

After initializing DocEditor 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 documents, spreadsheets, presentations, PDFs, and fillable forms from the outside.

info

This method is available only for ONLYOFFICE Docs Developer.

docEditor.createConnector();

denyEditingRights

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

docEditor.denyEditingRights(message);

Parameters:

ParameterTypePresenceDescription
messagestringoptionalThe text messages for dialog.

Example:

const message = "The document cannot be edited.";
docEditor.denyEditingRights(message);

destroyEditor

Destroy docEditor object. This method can be called when you want to reinit document editor with other configurations.

docEditor.destroyEditor();

downloadAs

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

docEditor.downloadAs(format);

Parameters:

ParameterTypePresenceDescription
formatstringoptionalThe format in which a file will be downloaded. All the possible formats you can find in the conversion tables. But you cannot download a file in the image formats such as bmp, gif, jpg, png. If this parameter is undefined, the file will be downloaded in the OOXML format according to the file type.
note

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

Example:

const format = "pdf";
docEditor.downloadAs(format);

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 event.

docEditor.insertImage(options);

Parameters:

ParameterTypePresenceDescription
options.cstringrequiredThe type of image insertion from the event: add, change, fill, watermark, slide. The default value is "add".
options.fileTypestringrequiredThe type of the image to be inserted into the file: bmp, gif, jpe, jpeg, jpg, png. Deprecated since version 7.0, please use the options.images.fileType parameter instead.
options.imagesobject[]requiredThe array of images to be inserted.
options.images.fileTypestringrequiredThe type of the image to be inserted into the file: bmp, gif, jpe, jpeg, jpg, png, tif, tiff.
options.images.urlstringrequiredThe absolute URL where the source image is stored. Be sure to add a token when using local links.
options.tokenstringoptionalThe encrypted signature added to the parameter in the form of a token.
options.urlstringrequiredThe absolute URL where the source image is stored. Be sure to add a token when using local links. Otherwise, an error will occur. Deprecated since version 7.0, please use the options.images.url parameter instead.

Example:

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",
});
note

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.

refreshFile

Updates the file version without reloading the editor. This method must be called after the onRequestRefreshFile event.

This method must take the editor initialization configuration for the current file version. The configuration must contain all the parameters used for signing a request to open a file for editing. The following parameters cannot be changed in the config: documentType, type, events.

docEditor.refreshFile(config);

Parameters:

ParameterTypePresenceDescription
configobjectrequiredThe editor initialization configuration for the current file version.

Example:

docEditor.refreshFile({
document: {
fileType: "docx",
key: "Khirz6zTPdfd7",
title: "Example Document Title.docx",
url: "https://example.com/url-to-example-document.docx",
},
documentType: "word",
editorConfig: {
callbackUrl: "https://example.com/url-to-callback",
},
token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb2N1bWVudCI6eyJmaWxlVHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3IiwidGl0bGUiOiJFeGFtcGxlIERvY3VtZW50IFRpdGxlLmRvY3giLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifSwiZG9jdW1lbnRUeXBlIjoid29yZCIsImVkaXRvckNvbmZpZyI6eyJjYWxsYmFja1VybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWNhbGxiYWNrLmFzaHgifX0.vbezS2aM8Xf8qFzIAsO-jrIsi7VLxjRYkIkwh5jLTJU",
});

refreshHistory

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

docEditor.refreshHistory(options);

Parameters:

ParameterTypePresenceDescription
options.currentVersionnumberrequiredThe current document version number.
options.errorstringoptionalThe error message text.
options.historyobject[]requiredThe array with the document versions.
options.history.changesobjectoptionalThe changes from the history object returned after saving the document.
options.history.createdstringrequiredThe document version creation date.
options.history.keystringrequiredThe unique document identifier used by the service to recognize the document.
options.history.serverVersionnumberoptionalThe current server version number. If the changes parameter is sent, then the serverVersion parameter is required to be sent as well.
options.history.userobjectoptionalThe user who is the author of the document version.
options.history.user.idstringoptionalThe identifier of the user who is the author of the document version.
options.history.user.namestringoptionalThe name of the user who is the author of the document version.
options.history.versionnumberrequiredThe document version number.

Example:

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: changes,
created: "2010-07-07 3:46 PM",
key: "Khirz6zTPdfd7",
serverVersion: 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.

If the version history cannot be displayed, send an error message:

docEditor.refreshHistory({
error: "Version history is not available.",
})

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();

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);

Parameters:

ParameterTypePresenceDescription
linkstringrequiredThe link which allows scrolling to the bookmark position in the document.

Example:

const link = "https://example.com/editor?bookmark=bookmark_ABC123";
docEditor.setActionLink(link);

setFavorite

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

docEditor.setFavorite(favorite);

Parameters:

ParameterTypePresenceDescription
favoritebooleanrequiredIf true, the Favorite icon is highlighted.

Example:

const favorite = true;
docEditor.setFavorite(favorite);

setHistoryData

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

docEditor.setHistoryData(options);

Parameters:

ParameterTypePresenceDescription
options.changesUrlstringoptionalThe url address of the file with the document changes data, which can be downloaded by the changesurl link from the JSON object returned after saving the document. The request for file is signed with a token which is checked by the ONLYOFFICE Docs.
options.errorstringoptionalThe error message text.
options.fileTypestringoptionalThe extension of the document specified with the url parameter.
options.keystringrequiredThe document identifier used to unambiguously identify the document file.
options.previousobjectoptionalThe object of the previous version of the document if changesUrl address was returned after saving the document.
options.previous.fileTypestringoptionalThe extension of the document specified with the options.previous.url parameter.
options.previous.keystringrequiredThe document identifier of the previous version of the document.
options.previous.urlstringrequiredThe url address of the previous version of the document.
options.tokenstringoptionalThe encrypted signature added to the parameter in the form of a token.
options.urlstringrequiredThe url address of the current document version. Can be downloaded by the url link from the JSON object returned after saving the document. Be sure to add a token when using local links. Otherwise, an error will occur.
options.versionnumberrequiredThe document version number.

Example:

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

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,
});

If the document version cannot be displayed, send an error message:

docEditor.setHistoryData({
error: "Document version data is not available.",
version: 2,
});

setMailMergeRecipients

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

Deprecated

Starting from version 7.5, please use setRequestedSpreadsheet instead.

docEditor.setMailMergeRecipients(options);

Parameters:

ParameterTypePresenceDescription
options.fileTypestringrequiredThe type of spreadsheet for mail merge in the file: csv, fods, ods, ots, xls, xlsm, xlsx, xlt, xltm, xltx.
options.tokenstringoptionalThe encrypted signature added to the parameter in the form of a token.
options.urlstringrequiredThe absolute URL where the source data is stored. Be sure to add a token when using local links. Otherwise, an error will occur.

Example:

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

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.

info

This method is available only for ONLYOFFICE Docs Developer.

note

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

docEditor.setReferenceData(options);

Parameters:

ParameterTypePresenceDescription
options.errorstringoptionalThe error message text.
options.fileTypestringoptionalThe extension of the document specified with the url parameter.
options.keystringoptionalThe unique document identifier used by the service to take the data from the co-editing session. In case the known key is sent, the document will be taken from the cache. Every time the document is edited and saved, the key must be generated anew. The document url can be used as the key but without the special characters and the length is limited to 128 symbol.
options.pathstringrequiredThe file name or relative path for the formula editor. It is used to identify a file when the onRequestReferenceData event is executed.
options.referenceDataobjectoptionalThe object that is generated by the integrator to uniquely identify a file in its system. This data must be the same as in the document.referenceData config parameter.
options.tokenstringoptionalThe encrypted signature added to the parameter in the form of a token.
options.urlstringrequiredThe URL address to download the current file.

Example:

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

If an error occurred, send an error message:

docEditor.setReferenceData({
error: "File data is not available.",
});

setReferenceSource

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

note

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

docEditor.setReferenceSource(options);

Parameters:

ParameterTypePresenceDescription
options.errorstringoptionalThe error message text.
options.fileTypestringoptionalThe extension of the document specified with the url parameter.
options.keystringoptionalThe unique document identifier used by the service to take the data from the co-editing session. In case the known key is sent, the document will be taken from the cache. Every time the document is edited and saved, the key must be generated anew. The document url can be used as the key but without the special characters and the length is limited to 128 symbol.
options.pathstringrequiredThe file name or relative path for the formula editor. It is used to identify a file when the onRequestReferenceSource event is executed.
options.referenceDataobjectoptionalThe object that is generated by the integrator to uniquely identify a file in its system. This data must be the same as in the document.referenceData config parameter.
options.tokenstringoptionalThe encrypted signature added to the parameter in the form of a token.
options.urlstringrequiredThe URL address to download the current file.

Example:

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

If an error occurred, send an error message:

docEditor.setReferenceSource({
error: "Reference source is not available.",
});

setRequestedDocument

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

docEditor.setRequestedDocument(options);

Parameters:

ParameterTypePresenceDescription
options.cstringrequiredThe type of document selection from the event: compare, combine, or insert-text. The default value is "compare".
options.fileTypestringrequiredThe type of the document to be selected: doc, docm, docx, dot, dotm, dotx, epub, fodt, odt, ott, rtf, wps.
options.tokenstringoptionalThe encrypted signature added to the parameter in the form of a token.
options.urlstringrequiredThe absolute URL where the source document is stored. Be sure to add a token when using local links. Otherwise, an error will occur.

Example:

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

setRequestedSpreadsheet

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

docEditor.setRequestedSpreadsheet(options);

Parameters:

ParameterTypePresenceDescription
options.cstringrequiredThe type of spreadsheet selection from the event: mailmerge.
options.fileTypestringrequiredThe type of spreadsheet for mail merge in the file: csv, fods, ods, ots, xls, xlsm, xlsx, xlt, xltm, xltx.
options.tokenstringoptionalThe encrypted signature added to the parameter in the form of a token.
options.urlstringrequiredThe absolute URL where the source data is stored. Be sure to add a token when using local links. Otherwise, an error will occur.

Example:

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

setRevisedFile

Select a document for comparing. This method must be called after the onRequestCompareFile event.

Deprecated

Starting from version 7.5, please use setRequestedDocument instead.

info

This method is available only for ONLYOFFICE Docs Enterprise and ONLYOFFICE Docs Developer.

docEditor.setRevisedFile(options);

Parameters:

ParameterTypePresenceDescription
options.fileTypestringrequiredThe type of document for comparing: doc, docm, docx, dot, dotm, dotx, epub, fodt, odt, ott, rtf, wps.
options.tokenstringoptionalThe encrypted signature added to the parameter in the form of a token.
options.urlstringrequiredThe absolute URL where the source document is stored. Be sure to add a token when using local links. Otherwise, an error will occur.

Example:

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

setSharingSettings

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

docEditor.setSharingSettings(options);

Parameters:

ParameterTypePresenceDescription
options.sharingSettingsobject[]optionalThe settings which allow sharing the document with other users.
options.sharingSettings.isLinkbooleanoptionalChanges the user icon to the link icon.
options.sharingSettings.permissionsstringoptionalThe access rights for the user with the name above.
options.sharingSettings.userstringoptionalThe name of the user with whom the document will be shared.

Example:

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 event.

docEditor.setUsers(options);

Parameters:

ParameterTypePresenceDescription
options.cstringrequiredThe operation type from the onRequestUsers event: mention, protect, or info. The default value is mention.
options.usersobject[]optionalThe list of the users.
options.users.emailstringoptionalThe email address of the user. This field is required when the c parameter is mention.
options.users.idstringoptionalThe identification of the user. This field is required when the c parameter is protect.
options.users.imagestringoptionalThe path to the user's avatar. This field is required when the c parameter is info.
options.users.namestringoptionalThe full name of the user.

Example:

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",
},
],
});
note

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,*****".

note

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 event.

docEditor.showMessage(message);

Parameters:

ParameterTypePresenceDescription
messagestringrequiredThe message text.

Example:

const message = "Changes have been saved successfully.";
docEditor.showMessage(message);
note

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();