Merge pull request 'Lifecycle of opening editor' from feature/lifecyc…

…le-editor-opening into feature/editor-8.3.0

Reviewed-on: https://git.onlyoffice.com/ONLYOFFICE/api.onlyoffice.com/pulls/113

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Change Log
 
+- docs api: added the Lifecycle of opening editor page
 - 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

site/pages/Docs/Docs API/Get Started/How It Works/Action link/index.md

@@ -1,5 +1,5 @@
 ---
-order: -17
+order: -18
 ---
 
 The reference figure and the steps below explain the process of working with links in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Anonymous users/index.md

@@ -1,5 +1,5 @@
 ---
-order: -10
+order: -11
 ---
 
 The reference figure and the steps below explain the process of setting a name to an anonymous user in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Checking PDF forms/index.md

@@ -1,5 +1,5 @@
 ---
-order: -1
+order: -2
 ---
 
 PDF forms differ from standard PDF files in form metadata. It determines which editor opens a file: the form editor or the standard PDF editor.

site/pages/Docs/Docs API/Get Started/How It Works/Co-editing/index.md

@@ -1,5 +1,5 @@
 ---
-order: -19
+order: -20
 ---
 
 The reference figure and the steps below explain the process of co-editing a document in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Commenting/index.md

@@ -1,5 +1,5 @@
 ---
-order: -9
+order: -10
 ---
 
 The **Comment option** allows you to leave comments on the specific words, phrases, sentences and other document parts, edit and remove these comments. All the comments will be saved and shown to other document users.

site/pages/Docs/Docs API/Get Started/How It Works/Comparing documents/index.md

@@ -1,5 +1,5 @@
 ---
-order: -8
+order: -9
 ---
 
 The reference figure and the steps below explain the process of comparing documents in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Converting and downloading file/index.md

@@ -1,5 +1,5 @@
 ---
-order: -12
+order: -13
 ---
 
 Document conversion service is a part of ONLYOFFICE Docs. It lets the user convert files from one format into another to open them later in **document editors** or for their export.

site/pages/Docs/Docs API/Get Started/How It Works/Document history/index.md

@@ -1,5 +1,5 @@
 ---
-order: -18
+order: -19
 ---
 
 You can view the history of text documents, spreadsheets or presentations using the **document editor**.

site/pages/Docs/Docs API/Get Started/How It Works/Embedding forms into a web page/index.md

@@ -1,5 +1,5 @@
 ---
-order: -4
+order: -5
 ---
 
 Starting from version 7.0, ONLYOFFICE Docs offers the possibility to create, edit and collaborate on online forms, fill them out, and save forms as PDF.

site/pages/Docs/Docs API/Get Started/How It Works/Inline editors/index.md

@@ -1,5 +1,5 @@
 ---
-order: -13
+order: -14
 ---
 
 The steps below explain the process of connecting several editors to the same html page in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Inserting external data/index.md

@@ -1,5 +1,5 @@
 ---
-order: -5
+order: -6
 ---
 
 The steps below explain the process of inserting data into the spreadsheet by an external link in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md

@@ -0,0 +1,181 @@
+---
+order: -1
+---
+
+The lifecycle of [opening](../Opening%20file/index.md) an editor can be defined by the sequence of the events.
+
+Add the script initializing the Document Editor with the configuration for the document you want to open:
+
+``` ts
+const docEditor = new DocsAPI.DocEditor("placeholder", {
+  document: {
+    fileType: "docx",
+    key: "Khirz6zTPdfd7",
+    title: "Example Document Title.docx",
+    url: "https://example.com/url-to-example-document.docx",
+  },
+  documentType: "word",
+  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkb2N1bWVudCI6eyJmaWxlVHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3IiwidGl0bGUiOiJFeGFtcGxlIERvY3VtZW50IFRpdGxlLmRvY3giLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifSwiZG9jdW1lbnRUeXBlIjoid29yZCJ9.7IpEJxdOvBQ0kJ8l6ZegIV4tX5vsPbZZCDDVmcFROXc",
+})
+```
+
+Specify there the following events:
+
+1. When the application is loaded into the browser, the [onAppReady](../../../Usage%20API/Config/Events/index.md#onappready) event is executed:
+
+   ``` ts
+   function onAppReady() {
+     console.log("ONLYOFFICE Document Editor is ready")
+   }
+
+   const docEditor = new DocsAPI.DocEditor("placeholder", {
+     events: {
+       onAppReady,
+     },
+   })
+   ```
+
+   After that, the [showMessage](../../../Usage%20API/Methods/index.md#showmessage) method can be called which displays a tooltip with a message:
+
+   ``` ts
+   docEditor.showMessage(message)
+   ```
+
+   ## message
+
+   Defines the message text.
+
+   Type: string
+
+   Presence: required
+
+  > Please note that displaying a tooltip with a message is not supported in the embedded platform [type](../../../Usage%20API/Config/index.md#type).
+
+2. When an error or some other specific event occurs, the [onError](../../../Usage%20API/Config/Events/index.md#onerror)  event is executed:
+
+   ``` ts
+   function onError(event) {
+     console.log(`ONLYOFFICE Document Editor reports an error: code ${event.data.errorCode}, description ${event.data.errorDescription}`)
+   }
+
+   const docEditor = new DocsAPI.DocEditor("placeholder", {
+     events: {
+       onError,
+     },
+   })
+   ```
+
+   For example, it may be a conversion error or an error loading a certain editor component. Further work will not be available.
+
+3. When the document is opened for editing with the old [document.key](../../../Usage%20API/Config/Document/index.md#key) value, which was used to edit the previous document version and was successfully saved, the [onOutdatedVersion](../../../Usage%20API/Config/Events/index.md#onoutdatedversion) event is executed:
+
+   ``` ts
+   function onOutdatedVersion() {
+     location.reload(true)
+   }
+
+   const docEditor = new DocsAPI.DocEditor("placeholder", {
+     events: {
+       onOutdatedVersion,
+     },
+   })
+   ```
+
+   An [error](../../../More%20Information/Troubleshooting/index.md#the-file-version-has-been-changed) will occur and further work will not be available. If the event is not processed, the file will be opened for viewing only. The editor must be reinitialized with a new key.
+
+   This event is deprecated since version 8.3. Please use the [onRequestRefreshFile](../../../Usage%20API/Config/Events/index.md#onrequestrefreshfile) event instead.
+
+   When the editor is opened with [key](../../../Usage%20API/Config/Document/index.md#key) that was already used to successfully save a file, the `onRequestRefreshFile` event is executed instead of the `onOutdatedVersion` event:
+
+   ``` 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: {
+       onRequestHistory,
+     },
+   })
+   ```
+
+   In this case, the [refreshFile](../../../Usage%20API/Methods/index.md#refreshfile) method is called and the file version is updated with a new key value without reloading the editor.
+
+4. When a user action is required to open a document, the [onUserActionRequired](../../../Usage%20API/Config/Events/index.md#onuseractionrequired) event is executed:
+
+   ``` ts
+   function onUserActionRequired() {
+     console.log("Enter a password")
+   }
+   const docEditor = new DocsAPI.DocEditor("placeholder", {
+     events: {
+       onUserActionRequired,
+     },
+   })
+   ```
+
+   This happens when  the user needs to enter a password to open the protected document or to select an encoding or a delimiter for the `txt` or `csv` files.
+
+5. When the document is loaded and the editor is ready for work, the [onDocumentReady](../../../Usage%20API/Config/Events/index.md#ondocumentready) event is executed:
+
+   ``` ts
+   function onDocumentReady() {
+     console.log("Document is loaded")
+   }
+
+   const docEditor = new DocsAPI.DocEditor("placeholder", {
+     events: {
+       onDocumentReady,
+     },
+   })
+   ```
+
+   After that, the requests to the [Automation API](../../../Usage%20API/Automation%20API/index.md) can be sent.
+
+   The `onOutdatedVersion` or `onRequestRefreshFile` events can be also called after the `onDocumentReady` event in the following case:
+
+   1. the document has been modified;
+   2. the Internet connection has been lost;
+   3. the document has been saved successfully;
+   4. the editor has reconnected to the server.
+
+6. When the user is trying to end the work with the editor and close it by clicking the cross button, the [onRequestClose](../../../Usage%20API/Config/Events/index.md#onrequestclose) event is executed:
+
+   ```ts
+   function onRequestClose() {
+     if (window.opener) {
+       window.close()
+       return
+     }
+     docEditor.destroyEditor()
+   }
+
+   const docEditor = new DocsAPI.DocEditor("placeholder", {
+     events: {
+       onRequestClose,
+     },
+   })
+   ```
+
+   The `onRequestClose` event can be also executed after the [requestClose](../../../Usage%20API/Methods/index.md#requestclose) method. It is recommended to call this method before the [destroyEditor](../../../Usage%20API/Methods/index.md#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:
+
+   ``` ts
+   docEditor.requestClose()
+   ```
+
+   The `destroyEditor` method is used to destroy `docEditor` object. This method can be called when you want to reinit document editor with another configurations:
+
+   ``` ts
+   docEditor.destroyEditor()
+   ```

site/pages/Docs/Docs API/Get Started/How It Works/Mentions/index.md

@@ -1,5 +1,5 @@
 ---
-order: -16
+order: -17
 ---
 
 The reference figure and the steps below explain the process of mentioning users in comments in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Mobile integration/index.md

@@ -1,5 +1,5 @@
 ---
-order: -6
+order: -7
 ---
 
 To access the editor features in your mobile application, integrate it with ONLYOFFICE editors via the WebView component - a system component that is responsible for opening web pages within applications. After that, users will be able to view, create and edit text documents, spreadsheets, and presentations, fill out and read PDFs directly on their iOS or Android devices.

site/pages/Docs/Docs API/Get Started/How It Works/Opening file/index.md

@@ -1,5 +1,5 @@
 ---
-order: -21
+order: -22
 ---
 
 The reference figure and the steps below explain the process of opening a document in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Protecting ranges/index.md

@@ -1,5 +1,5 @@
 ---
-order: -3
+order: -4
 ---
 
 The reference figure and the steps below explain the process of protecting ranges in spreadsheets in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Renaming files/index.md

@@ -1,5 +1,5 @@
 ---
-order: -15
+order: -16
 ---
 
 The reference figure and the steps below explain the process of renaming a document in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Reviewing/index.md

@@ -1,5 +1,5 @@
 ---
-order: -14
+order: -15
 ---
 
 The **Review option** allows you to review a document, change sentences, phrases and other page elements, correct spelling, etc. without actually editing it. All the changes will be recorded and shown to the user who created the document.

site/pages/Docs/Docs API/Get Started/How It Works/Saving file/index.md

@@ -1,5 +1,5 @@
 ---
-order: -20
+order: -21
 ---
 
 The reference figure and the steps below explain the process of saving a document in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Security/index.md

@@ -1,5 +1,5 @@
 ---
-order: -11
+order: -12
 ---
 
 To prevent the substitution of important parameters in ONLYOFFICE Docs requests an encrypted signature is added to it in the form of **token**.

site/pages/Docs/Docs API/Get Started/How It Works/Setting avatars/index.md

@@ -1,5 +1,5 @@
 ---
-order: -2
+order: -3
 ---
 
 The reference figure and the steps below explain the process of setting the avatars for the users in ONLYOFFICE Docs.

site/pages/Docs/Docs API/Get Started/How It Works/Viewing/index.md

@@ -1,5 +1,5 @@
 ---
-order: -7
+order: -8
 ---
 
 The viewing opening mode allows the user to view the document only without modifying its data. In order to enable this mode, the [editorConfig.mode](../../../Usage%20API/Config/Editor/index.md#mode) parameter must be set to **view**.

site/pages/Docs/Docs API/Get Started/How It Works/index.md

@@ -27,6 +27,7 @@ In this section you will learn how to:
 - [Protecting ranges](Protecting%20ranges/index.md)
 - [Setting avatars](Setting%20avatars/index.md)
 - [Checking PDF forms](Checking%20PDF%20forms/index.md)
+- [Lifecycle of opening editor](Lifecycle%20of%20opening%20editor/index.md)
 
 ## User-document interaction