Docs API: added the onRequestRefreshFile event and the refreshFile me…

…thod

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Change Log
 
+- docs api: added the refreshFile method
+- docs api: added the events.onRequestRefreshFile event
 - docs api: the editorConfig.customization.submitForm parameter can now be used as an object
 - docs api: the editorConfig.customization.compactToolbar parameter is now available for the viewer
 - docs api: added the editorConfig.customization.pointerMode parameter

site/pages/Docs/Docs API/More Information/Changelog/index.md

@@ -2,6 +2,8 @@ The list of changes of ONLYOFFICE Docs API.
 
 ## Version 8.3
 
+- Added the [refreshFile](../../Usage%20API/Methods/index.md#refreshfile) method.
+- Added the [events.onRequestRefreshFile](../../Usage%20API/Config/Events/index.md#onrequestrefreshfile) event.
 - The [editorConfig.customization.submitForm](../../Usage%20API/Config/Editor/Customization/index.md#submitform) parameter can now be used as an object.
 - The [editorConfig.customization.compactToolbar](../../Usage%20API/Config/Editor/Customization/index.md#compacttoolbar) parameter is now available for the viewer.
 - Added the [editorConfig.customization.pointerMode](../../Usage%20API/Config/Editor/Customization/index.md#pointermode) parameter.

site/pages/Docs/Docs API/More Information/Troubleshooting/index.md

@@ -32,9 +32,9 @@ Check if the [Callback handler](../../Usage%20API/Callback%20handler/index.md#ne
 
 ![The file version has been changed](/assets/images/editor/e-key.png)
 
-The editor is loaded with the "The file version has been changed. The page will be reloaded" message.
+The editor displays the "Connection is lost. Trying to connect. Please check connection settings." message.
 
-The **document editing service** cannot open the previously edited and saved file for editing.
+The **document editing service** is trying to update the file version without reloading the editor after the connection is lost.
 
 Do not forget that every time the document is edited and saved, the [document.key](../../Usage%20API/Config/Document/index.md#key) must be generated anew.
 

site/pages/Docs/Docs API/Usage API/Advanced parameters/index.md

@@ -296,6 +296,7 @@ const config = {
     onRequestOpen,
     onRequestReferenceData,
     onRequestReferenceSource,
+    onRequestRefreshFile,
     onRequestRename,
     onRequestRestore,
     onRequestSaveAs,

site/pages/Docs/Docs API/Usage API/Config/Events/index.md

@@ -24,6 +24,7 @@ The events section allows to change all the functions pertaining to the events.
 - [onRequestOpen](#onrequestopen) - the user is trying to open an external link.
 - [onRequestReferenceData](#onrequestreferencedata) - the user is trying to refresh data inserted from the external file by clicking the *Update values* button in the *External* links dialog box of the *Data* tab.
 - [onRequestReferenceSource](#onrequestreferencesource) - the user is trying to change an external link by clicking the *Change source* button.
+- [onRequestRefreshFile](#onrequestrefreshfile) - the file version is updated without reloading the editor.
 - [onRequestRename](#onrequestrename) - the user is trying to rename the file by clicking the *Rename...* button.
 - [onRequestRestore](#onrequestrestore) - the user is trying to restore the file version by clicking the *Restore* button in the version history.
 - [onRequestSaveAs](#onrequestsaveas) - the user is trying to save file by clicking *Save Copy as...* button.
@@ -217,7 +218,7 @@ const docEditor = new DocsAPI.DocEditor("placeholder", {
 
 ## onOutdatedVersion
 
-The function called after the [error](../../../More%20Information/Troubleshooting/index.md#key) is shown, when the document is opened for editing with the old [document.key](../Document/index.md#key) value, which was used to edit the previous document version and was successfully saved. When this event is called the editor must be reinitialized with a new *document.key*.
+The function called after the [error](../../../More%20Information/Troubleshooting/index.md#key) is shown, when the document is opened for editing with the old [document.key](../Document/index.md#key) value, which was used to edit the previous document version and was successfully saved. When this event is called the editor must be reinitialized with a new *document.key*. Deprecated since version 8.3, please use [onRequestRefreshFile](#onrequestrefreshfile) instead.
 
 Example:
 
@@ -590,6 +591,40 @@ const docEditor = new DocsAPI.DocEditor("placeholder", {
 })
 ```
 
+## onRequestRefreshFile
+
+The function called instead of the [onOutdatedVersion](#onoutdatedversion) event in the following cases:
+
+- when the editor is opened with [key](../Document/index.md#key) that was already used to successfully save a file;
+- when the editor reconnects to the server after losing the connection and interrupting the editing session.
+
+In these cases, the [refreshFile](../../Methods/index.md#refreshfile) method is called and the file version is updated without reloading the editor.
+
+Example:
+
+``` ts
+function onRequestRefreshFile() {
+  refreshFile({
+    document: {
+      key: "Khirz6zTPdfd7",
+      title: "Example Document Title.docx",
+      url: "https://example.com/url-to-example-document.docx",
+      permissions: {},
+    },
+    editorConfig: {
+      callbackUrl: "https://example.com/url-to-callback.ashx",
+      mode: "edit",
+    },
+    token: "...",
+  })
+}
+const docEditor = new DocsAPI.DocEditor("placeholder", {
+  events: {
+    onRequestRefreshFile,
+  },
+})
+```
+
 ## onRequestRename
 
 The function called when the user is trying to rename the file by clicking the *Rename...* button.

site/pages/Docs/Docs API/Usage API/Methods/index.md

@@ -13,6 +13,7 @@ const docEditor = new DocsAPI.DocEditor("placeholder", config)
 - [destroyEditor](#destroyeditor) - destroy *docEditor* object.
 - [downloadAs](#downloadas) - download the edited file.
 - [insertImage](#insertimage) - insert an image into the file.
+- [refreshFile](#refreshfile) - update the file version without reloading the editor.
 - [refreshHistory](#refreshhistory) - show the document version history.
 - [requestClose](#requestclose) - request to close the editor.
 - [setActionLink](#setactionlink) - set the link to the document which contains a bookmark.
@@ -118,6 +119,28 @@ Where **example.com** is the name of the server where **document manager** and *
   >
   > 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](../Config/Events/index.md#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](../../Additional%20API/Signature/Browser/index.md#opening-file) for editing. The following parameters cannot be changed in the config: [documentType](../Config/index.md#documenttype), [type](../Config/index.md#type), [events](../Config/Events/index.md).
+
+``` ts
+refreshFile({
+  document: {
+    key: "Khirz6zTPdfd7",
+    title: "Example Document Title.docx",
+    url: "https://example.com/url-to-example-document.docx",
+    permissions: {},
+  },
+  editorConfig: {
+    callbackUrl: "https://example.com/url-to-callback.ashx",
+    mode: "edit",
+  },
+  token: "...",
+})
+```
+
 ## refreshHistory
 
 Show the document version history. This method must be called after the [onRequestHistory](../Config/Events/index.md#onrequesthistory) events.