Merge remote-tracking branch 'remotes/origin/feature/editor-8.3.0' in…

…to feature/mobile-info # Conflicts: # CHANGELOG.md # site/pages/Docs/Docs API/More Information/Changelog/index.md
ONLYOFFICE · Dec 24, 2024 · a655042 · a655042
2 parents 6d69a5a + cbd0f22
commit a655042
Show file tree

Hide file tree

Showing 12 changed files with 231 additions and 25 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,10 @@
 # Change Log
 
 - docs api: added the editorConfig.customization.mobile.info parameter
+- docs api: added opening for pages, key, numbers formats
+- docs api: added the events.onUserActionRequired event
+- docs api: added the refreshFile method
+- docs api: added the events.onRequestRefreshFile event
 - docs api: the document editing will be prohibited for all users editing the document with the specified key, if the users parameter is not specified for the drop command
 - 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

diff --git a/site/assets/images/editor/e-key.png b/site/assets/images/editor/e-key.png
diff --git a/site/config.yml b/site/config.yml
@@ -36,7 +36,7 @@ playground:
     - path: document.fileType
       href: docs/docs-api/usage-api/config/document/#fileType
       type: string
-      cases: [docx, doc, odt, txt, xlsx, xls, ods, csv, pptx, ppsx, ppt, odp, pdf]
+      cases: [docx, doc, pages, odt, txt, xlsx, xls, ods, numbers, csv, pptx, ppsx, ppt, key, odp, pdf]
       default: docx
 
     - path: document.key
@@ -1371,6 +1371,26 @@ playground:
         events:
           onAppReady: console.log("Document Editor is ready")
 
+    - name: Open PAGES for viewing
+      configs:
+      - document:
+          fileType: pages
+          key: 9B9F6EFE8937
+          title: Example Document Title.pages
+          url: "https://example.com/url-to-example-document.pages"
+        documentType: word
+        editorConfig:
+          customization:
+            anonymous:
+              request: false
+              label: Guest
+            integrationMode: embed
+          mode: view
+        height: 700px
+        width: 100%
+        events:
+          onAppReady: console.log("Document Editor is ready")
+
     - name: Open XLSX for viewing
       configs:
       - document:
@@ -1391,6 +1411,26 @@ playground:
         events:
           onAppReady: console.log("Document Editor is ready")
 
+    - name: Open NUMBERS for viewing
+      configs:
+      - document:
+          fileType: numbers
+          key: 138E9734B413
+          title: Example Spreadsheet Title.numbers
+          url: "https://example.com/url-to-example-spreadsheet.numbers"
+        documentType: cell
+        editorConfig:
+          customization:
+            anonymous:
+              request: false
+              label: Guest
+            integrationMode: embed
+          mode: view
+        height: 700px
+        width: 100%
+        events:
+          onAppReady: console.log("Document Editor is ready")
+
     - name: Open PPTX for viewing
       configs:
       - document:
@@ -1411,6 +1451,26 @@ playground:
         events:
           onAppReady: console.log("Document Editor is ready")
 
+    - name: Open KEY for viewing
+      configs:
+      - document:
+          fileType: key
+          key: 37195B2B9BF4
+          title: Example Presentation Title.key
+          url: "https://example.com/url-to-example-presentation.key"
+        documentType: slide
+        editorConfig:
+          customization:
+            anonymous:
+              request: false
+              label: Guest
+            integrationMode: embed
+          mode: view
+        height: 700px
+        width: 100%
+        events:
+          onAppReady: console.log("Document Editor is ready")
+
     - name: Open DOCX for rebranding
       configs:
       - document:

diff --git a/site/pages/Docs/Docs API/Additional API/Conversion API/Conversion tables/index.md b/site/pages/Docs/Docs API/Additional API/Conversion API/Conversion tables/index.md
@@ -26,6 +26,7 @@ Below you can find tables with formats that are available for conversion in diff
 | odt   | +   | +    | +    | +     | +    | +    | +    | +   | +   | +    | +   |     | +   | +   | +    | +   | +   | +   |
 | ott   | +   | +    | +    | +     | +    | +    | +    | +   | +   | +    |     | +   | +   | +   | +    | +   | +   | +   |
 | oxps  | +   | +    | +    | +     | +    | +    | +    | +   | +   | +    | +   | +   | +   | +   | +    | +   | +   | +   |
+| pages | +   | +    | +    | +     | +    | +    | +    | +   | +   | +    | +   | +   | +   | +   | +    | +   | +   | +   |
 | pdf   | +   | +    | +    | +     | +    | +    | +    | +   | +   | +    | +   | +   | +   |     | +    | +   | +   | +   |
 | rtf   | +   | +    | +    | +     | +    | +    | +    | +   | +   | +    | +   | +   | +   | +   | +    | +   |     | +   |
 | stw   | +   | +    | +    | +     | +    | +    | +    | +   | +   | +    | +   | +   | +   | +   | +    | +   | +   | +   |
@@ -38,23 +39,24 @@ Below you can find tables with formats that are available for conversion in diff
 
 ## Spreadsheet file formats
 
-|      | bmp | csv | gif | jpg | ods | ots | pdf | pdfa | png | xlsm | xlsx | xltm | xltx |
-| ---- | --- | --- | --- | --- | --- | --- | --- | ---- | --- | ---- | ---- | ---- | ---- |
-| csv  | +   |     | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
-| et   | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
-| ett  | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
-| fods | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
-| ods  | +   | +   | +   | +   |     | +   | +   | +    | +   | +    | +    | +    | +    |
-| ots  | +   | +   | +   | +   | +   |     | +   | +    | +   | +    | +    | +    | +    |
-| sxc  | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
-| xls  | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
-| xlsb | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
-| xlsm | +   | +   | +   | +   | +   | +   | +   | +    | +   |      | +    | +    | +    |
-| xlsx | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    |      | +    | +    |
-| xlt  | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
-| xltm | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    |      | +    |
-| xltx | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    |      |
-| xml  | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+|         | bmp | csv | gif | jpg | ods | ots | pdf | pdfa | png | xlsm | xlsx | xltm | xltx |
+| ------- | --- | --- | --- | --- | --- | --- | --- | ---- | --- | ---- | ---- | ---- | ---- |
+| csv     | +   |     | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| et      | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| ett     | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| fods    | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| numbers | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| ods     | +   | +   | +   | +   |     | +   | +   | +    | +   | +    | +    | +    | +    |
+| ots     | +   | +   | +   | +   | +   |     | +   | +    | +   | +    | +    | +    | +    |
+| sxc     | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| xls     | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| xlsb    | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| xlsm    | +   | +   | +   | +   | +   | +   | +   | +    | +   |      | +    | +    | +    |
+| xlsx    | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    |      | +    | +    |
+| xlt     | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
+| xltm    | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    |      | +    |
+| xltx    | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    |      |
+| xml     | +   | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    |
 
 ## Presentation file formats
 
@@ -63,6 +65,7 @@ Below you can find tables with formats that are available for conversion in diff
 | dps  | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    | +    | +    |
 | dpt  | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    | +    | +    |
 | fodp | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    | +    | +    |
+| key  | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    | +    | +    |
 | odp  | +   | +   | +   |     | +   | +   | +    | +   | +    | +    | +    | +    | +    | +    |
 | otp  | +   | +   | +   | +   |     | +   | +    | +   | +    | +    | +    | +    | +    | +    |
 | pot  | +   | +   | +   | +   | +   | +   | +    | +   | +    | +    | +    | +    | +    | +    |

diff --git a/site/pages/Docs/Docs API/Additional API/Signature/Browser/index.md b/site/pages/Docs/Docs API/Additional API/Signature/Browser/index.md
@@ -85,6 +85,59 @@ Sample token:
 }
 ```
 
+### refreshFile
+
+When calling the [refreshFile](../../../Usage%20API/Methods/index.md#refreshFile) method to update the file version, the token must be added to validate the parameters.
+
+The `payload` for the JWT token in the JSON format must have the same structure as the [config](../../../Usage%20API/Advanced%20parameters/index.md).
+
+  ``` json
+  {
+    "document": {
+      "key": "Khirz6zTPdfd7",
+      "permissions": {
+        "comment": true,
+        "commentGroups": {
+          "edit": ["Group2", ""],
+          "remove": [""],
+          "view": ""
+        },
+        "copy": true,
+        "deleteCommentAuthorOnly": false,
+        "download": true,
+        "edit": true,
+        "editCommentAuthorOnly": false,
+        "fillForms": true,
+        "modifyContentControl": true,
+        "modifyFilter": true,
+        "print": true,
+        "review": true,
+        "reviewGroups": ["Group1", "Group2", ""]
+      },
+      "url": "https://example.com/url-to-example-document.docx"
+    },
+    "editorConfig": {
+      "callbackUrl": "https://example.com/url-to-callback.ashx",
+      "mode": "edit",
+      "user": {
+        "group": "Group1",
+        "id": "78e1e841",
+        "name": "Smith"
+      }
+    }
+  }
+  ```
+
+Where **example.com** is the name of the server where **document manager** and **document storage service** are installed. See the [How it works](../../../Get%20Started/How%20It%20Works/index.md) section to find out more on ONLYOFFICE Docs service client-server interactions.
+
+Sample token:
+
+``` json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb2N1bWVudCI6eyJrZXkiOiJLaGlyejZ6VFBkZmQ3IiwicGVybWlzc2lvbnMiOnsiY29tbWVudCI6dHJ1ZSwiY29tbWVudEdyb3VwcyI6eyJlZGl0IjpbIkdyb3VwMiIsIiJdLCJyZW1vdmUiOlsiIl0sInZpZXciOiIifSwiY29weSI6dHJ1ZSwiZGVsZXRlQ29tbWVudEF1dGhvck9ubHkiOmZhbHNlLCJkb3dubG9hZCI6dHJ1ZSwiZWRpdCI6dHJ1ZSwiZWRpdENvbW1lbnRBdXRob3JPbmx5IjpmYWxzZSwiZmlsbEZvcm1zIjp0cnVlLCJtb2RpZnlDb250ZW50Q29udHJvbCI6dHJ1ZSwibW9kaWZ5RmlsdGVyIjp0cnVlLCJwcmludCI6dHJ1ZSwicmV2aWV3Ijp0cnVlLCJyZXZpZXdHcm91cHMiOlsiR3JvdXAxIiwiR3JvdXAyIiwiIl19LCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifSwiZWRpdG9yQ29uZmlnIjp7ImNhbGxiYWNrVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tY2FsbGJhY2suYXNoeCIsIm1vZGUiOiJlZGl0IiwidXNlciI6eyJncm91cCI6Ikdyb3VwMSIsImlkIjoiNzhlMWU4NDEiLCJuYW1lIjoiU21pdGgifX19.irYst9vmsLoQtC-95A-6W8DnbqGXCbmcxJajfbPh6tQ"
+}
+```
+
 ### setHistoryData
 
 When calling the [setHistoryData](../../../Usage%20API/Methods/index.md#sethistorydata) method to view the document [history](../../../Get%20Started/How%20It%20Works/Document%20history/index.md) version in ONLYOFFICE Docs, the token must be added to validate the parameters.

diff --git a/site/pages/Docs/Docs API/More Information/Changelog/index.md b/site/pages/Docs/Docs API/More Information/Changelog/index.md
@@ -3,6 +3,10 @@ The list of changes of ONLYOFFICE Docs API.
 ## Version 8.3
 
 - Added the [editorConfig.customization.mobile.info](../../Usage%20API/Config/Editor/Customization/index.md#mobileinfo) parameter.
+- Added opening for [pages, key, numbers](../../Usage%20API/Config/index.md#documenttype) formats.
+- Added the [events.onUserActionRequired](../../Usage%20API/Config/Events/index.md#onuseractionrequired) event.
+- Added the [refreshFile](../../Usage%20API/Methods/index.md#refreshfile) method.
+- Added the [events.onRequestRefreshFile](../../Usage%20API/Config/Events/index.md#onrequestrefreshfile) event.
 - The document editing will be prohibited for all users editing the document with the specified *key*, if the *users* parameter is not specified for the [drop](../../Additional%20API/Command%20service/drop/index.md) command.
 - 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.

diff --git a/site/pages/Docs/Docs API/More Information/Troubleshooting/index.md b/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.
 

diff --git a/site/pages/Docs/Docs API/Usage API/Advanced parameters/index.md b/site/pages/Docs/Docs API/Usage API/Advanced parameters/index.md
@@ -297,6 +297,7 @@ const config = {
     onRequestOpen,
     onRequestReferenceData,
     onRequestReferenceSource,
+    onRequestRefreshFile,
     onRequestRename,
     onRequestRestore,
     onRequestSaveAs,
@@ -307,6 +308,7 @@ const config = {
     onRequestStartFilling,
     onRequestUsers,
     onSubmit,
+    onUserActionRequired,
     onWarning,
   },
   height: "100%",

diff --git a/site/pages/Docs/Docs API/Usage API/Config/Document/index.md b/site/pages/Docs/Docs API/Usage API/Config/Document/index.md
@@ -2,7 +2,7 @@ The document section allows to change all the parameters pertaining to the docum
 
 ## fileType
 
-Defines the type of the file for the source viewed or edited document. Must be lowercase. The following file types are available: *.csv, .djvu, .doc, .docm, .docx, .docxf, .dot, .dotm, .dotx, .epub, .fb2, .fodp, .fods, .fodt, .htm, .html, .mht, .odp, .ods, .odt, .oform, .otp, .ots, .ott, .oxps, .pdf, .pot, .potm, .potx, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf, .txt, .xls, .xlsb, .xlsm, .xlsx, .xlt, .xltm, .xltx, .xml, .xps*.
+Defines the type of the file for the source viewed or edited document. Must be lowercase. The following file types are available: *.csv, .djvu, .doc, .docm, .docx, .docxf, .dot, .dotm, .dotx, .epub, .fb2, .fodp, .fods, .fodt, .htm, .html, .key, .mht, .numbers, .odp, .ods, .odt, .oform, .otp, .ots, .ott, .oxps, .pages, .pdf, .pot, .potm, .potx, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf, .txt, .xls, .xlsb, .xlsm, .xlsx, .xlt, .xltm, .xltx, .xml, .xps*.
 
 > This parameter is required.
 

diff --git a/site/pages/Docs/Docs API/Usage API/Config/Events/index.md b/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.
@@ -34,6 +35,7 @@ The events section allows to change all the functions pertaining to the events.
 - [onRequestStartFilling](#onrequeststartfilling) - the user is trying to start filling out the ready forms by clicking the *Start filling* button in the pdf editing mode.
 - [onRequestUsers](#onrequestusers) - the user can select other users to mention in the comments, grant the access rights to edit the specific sheet ranges, or set the user avatars.
 - [onSubmit](#onsubmit) - the force saving request of the *3* [forcesavetype](../../Callback%20handler/index.md#forcesavetype) is successfully performed.
+- [onUserActionRequired](#onuseractionrequired) - a user action is required to open a document.
 - [onWarning](#onwarning) - a warning occurs.
 
 ## onAppReady
@@ -217,7 +219,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 +592,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: {
+      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.ashx",
+    },
+    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb2N1bWVudCI6eyJmaWxlVHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3IiwidGl0bGUiOiJFeGFtcGxlIERvY3VtZW50IFRpdGxlLmRvY3giLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifSwiZG9jdW1lbnRUeXBlIjoid29yZCIsImVkaXRvckNvbmZpZyI6eyJjYWxsYmFja1VybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWNhbGxiYWNrLmFzaHgifX0.vbezS2aM8Xf8qFzIAsO-jrIsi7VLxjRYkIkwh5jLTJU",
+  })
+}
+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.
@@ -905,6 +941,27 @@ const docEditor = new DocsAPI.DocEditor("placeholder", {
 })
 ```
 
+## onUserActionRequired
+
+The function called when a user action is required to open a document in the following cases:
+
+- when the user needs to enter a password to open the protected document;
+- when the user needs to select an encoding for the *txt* file;
+- when the user needs to select an encoding and a delimiter for the *csv* file.
+
+Example:
+
+``` ts
+function onUserActionRequired() {
+  console.log("Enter a password")
+}
+const docEditor = new DocsAPI.DocEditor("placeholder", {
+  events: {
+    onUserActionRequired,
+  },
+})
+```
+
 ## onWarning
 
 The function called when a warning occurs. The warning message is sent in the *data* parameter. A list of error codes can be found [here](https://github.com/ONLYOFFICE/sdkjs/blob/master/common/errorCodes.js).