From b5df9b68ecec46aada1d6751822acfe36e6b18ab Mon Sep 17 00:00:00 2001 From: NataliaOvchinnikova Date: Thu, 26 Dec 2024 17:50:13 +0300 Subject: [PATCH 1/2] docs api: added the Lifecycle of opening editor page --- CHANGELOG.md | 1 + .../How It Works/Action link/index.md | 2 +- .../How It Works/Anonymous users/index.md | 2 +- .../How It Works/Checking PDF forms/index.md | 2 +- .../How It Works/Co-editing/index.md | 2 +- .../How It Works/Commenting/index.md | 2 +- .../How It Works/Comparing documents/index.md | 2 +- .../Converting and downloading file/index.md | 2 +- .../How It Works/Document history/index.md | 2 +- .../Embedding forms into a web page/index.md | 2 +- .../How It Works/Inline editors/index.md | 2 +- .../Inserting external data/index.md | 2 +- .../Lifecycle of opening editor/index.md | 177 ++++++++++++++++++ .../How It Works/Mentions/index.md | 2 +- .../How It Works/Mobile integration/index.md | 2 +- .../How It Works/Opening file/index.md | 2 +- .../How It Works/Protecting ranges/index.md | 2 +- .../How It Works/Renaming files/index.md | 2 +- .../How It Works/Reviewing/index.md | 2 +- .../How It Works/Saving file/index.md | 2 +- .../How It Works/Security/index.md | 2 +- .../How It Works/Setting avatars/index.md | 2 +- .../Get Started/How It Works/Viewing/index.md | 2 +- .../Get Started/How It Works/index.md | 1 + 24 files changed, 200 insertions(+), 21 deletions(-) create mode 100644 site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ea20c6f80..f568e8e95 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Action link/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Action link/index.md index df861b499..513618351 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Action link/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Anonymous users/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Anonymous users/index.md index 6f469ab9c..3f7274aa5 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Anonymous users/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Checking PDF forms/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Checking PDF forms/index.md index 6709b22a1..7f1b2870a 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Checking PDF forms/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Co-editing/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Co-editing/index.md index 0738ee149..d4802be80 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Co-editing/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Commenting/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Commenting/index.md index 1ff2fd273..913fc7610 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Commenting/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Comparing documents/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Comparing documents/index.md index 20f409632..83b322c61 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Comparing documents/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Converting and downloading file/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Converting and downloading file/index.md index ecb923f8f..7564b527e 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Converting and downloading file/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Document history/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Document history/index.md index 3ea73bff5..f27008385 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Document history/index.md +++ b/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**. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Embedding forms into a web page/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Embedding forms into a web page/index.md index 5598be724..0060bd54c 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Embedding forms into a web page/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Inline editors/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Inline editors/index.md index 118a6feba..c28b91593 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Inline editors/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Inserting external data/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Inserting external data/index.md index 2cd87db4b..57770dc50 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Inserting external data/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md new file mode 100644 index 000000000..55e338a90 --- /dev/null +++ b/site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md @@ -0,0 +1,177 @@ +--- +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) + ``` + + | Parameter | Type | Presence | Description | + | --------- | ------ | -------- | ------------------------- | + | message | string | required | Defines the message text. | + + > 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() + ``` diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Mentions/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Mentions/index.md index bea91d7f0..a9526b557 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Mentions/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Mobile integration/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Mobile integration/index.md index 4a270223c..1407bdad6 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Mobile integration/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Opening file/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Opening file/index.md index d6d778da0..c48d3d10a 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Opening file/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Protecting ranges/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Protecting ranges/index.md index 7044afa9c..dbf8c26a0 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Protecting ranges/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Renaming files/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Renaming files/index.md index 5613cfb67..6e11f3dd3 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Renaming files/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Reviewing/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Reviewing/index.md index c16f431cc..d4dbe3287 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Reviewing/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Saving file/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Saving file/index.md index 928e16db5..eb75035e8 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Saving file/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Security/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Security/index.md index a3cbf564d..fad930e07 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Security/index.md +++ b/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**. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Setting avatars/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Setting avatars/index.md index 5db1dc993..70a67ea49 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Setting avatars/index.md +++ b/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. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Viewing/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Viewing/index.md index 15e5aec55..6e68028e4 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Viewing/index.md +++ b/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**. diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/index.md index c80a8127a..fe89b0211 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/index.md +++ b/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 From 6e36b0df602f6a014e3ec8b19588bd4881acc3f9 Mon Sep 17 00:00:00 2001 From: NataliaOvchinnikova Date: Fri, 27 Dec 2024 14:15:03 +0300 Subject: [PATCH 2/2] change parameters style --- .../Lifecycle of opening editor/index.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md b/site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md index 55e338a90..fe5f6c60c 100644 --- a/site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md +++ b/site/pages/Docs/Docs API/Get Started/How It Works/Lifecycle of opening editor/index.md @@ -41,11 +41,15 @@ Specify there the following events: docEditor.showMessage(message) ``` - | Parameter | Type | Presence | Description | - | --------- | ------ | -------- | ------------------------- | - | message | string | required | Defines the message text. | - - > Please note that displaying a tooltip with a message is not supported in the embedded platform [type](../../../Usage%20API/Config/index.md#type). + ## 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: