[Libreoffice-commits] online.git: 2 commits - loleaflet/README loolwsd.spec.in Makefile.am wsd/reference.md wsd/reference.txt
Libreoffice Gerrit user
logerrit at kemper.freedesktop.org
Wed Nov 7 20:25:54 UTC 2018
Makefile.am | 2
loleaflet/README | 8 +-
loolwsd.spec.in | 2
wsd/reference.md | 163 +++++++++++++++++++++++++++++++++++++++++++++
wsd/reference.txt | 192 ------------------------------------------------------
5 files changed, 169 insertions(+), 198 deletions(-)
New commits:
commit 2bf384cac0a320df247a9d15979761dae30a710f
Author: Andras Timar <andras.timar at collabora.com>
AuthorDate: Wed Nov 7 21:25:25 2018 +0100
Commit: Andras Timar <andras.timar at collabora.com>
CommitDate: Wed Nov 7 21:25:25 2018 +0100
Convert wsd/reference.txt to Markdown format
Change-Id: I393a74337293e376b6458a9cc05ba1d8b748e0d3
diff --git a/Makefile.am b/Makefile.am
index 50b9bf0ab..6e537309e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -31,7 +31,7 @@ man_MANS = man/loolwsd.1 \
dist_doc_DATA = wsd/README \
wsd/README.vars \
wsd/protocol.txt \
- wsd/reference.txt
+ wsd/reference.md
loolwsddatadir = @LOOLWSD_DATADIR@
diff --git a/loleaflet/README b/loleaflet/README
index afc29f8c2..3b9f53d21 100644
--- a/loleaflet/README
+++ b/loleaflet/README
@@ -129,10 +129,10 @@ src/control/Toolbar.js . Any new test file needs also to be added in spec/leafle
API & events
------------
-######################################################################
-# See /loleaflet/reference.html for a better formated documentation. #
-# See /wsd/reference.txt for the HTTP API documentation. #
-######################################################################
+#######################################################################
+# See /loleaflet/reference.html for a better formatted documentation. #
+# See /wsd/reference.md for the HTTP API documentation. #
+#######################################################################
Search:
- API:
diff --git a/loolwsd.spec.in b/loolwsd.spec.in
index b1d2df5fb..929bff10b 100644
--- a/loolwsd.spec.in
+++ b/loolwsd.spec.in
@@ -105,7 +105,7 @@ echo "account required pam_unix.so" >> %{buildroot}/etc/pam.d/loolwsd
/usr/share/doc/loolwsd/README
/usr/share/doc/loolwsd/README.vars
/usr/share/doc/loolwsd/protocol.txt
-/usr/share/doc/loolwsd/reference.txt
+/usr/share/doc/loolwsd/reference.md
/usr/share/man/man1/loolwsd.1
/usr/share/man/man1/loolforkit.1
/usr/share/man/man1/loolconvert.1
commit a9cf1ab45fbed65c66eb3159ca976fc877f1f63e
Author: Andras Timar <andras.timar at collabora.com>
AuthorDate: Wed Nov 7 21:21:59 2018 +0100
Commit: Andras Timar <andras.timar at collabora.com>
CommitDate: Wed Nov 7 21:22:33 2018 +0100
Convert wsd/reference.txt to Markdown format
Change-Id: I93b36c7136a9ea77ecf381fb1c57913c283821b6
diff --git a/wsd/reference.md b/wsd/reference.md
new file mode 100644
index 000000000..194c8571b
--- /dev/null
+++ b/wsd/reference.md
@@ -0,0 +1,163 @@
+
+LibreOffice Online API
+======================
+
+Document conversion
+-------------------
+
+ **API:** HTTP POST to `/lool/convert-to/<format>`
+ * the format is e.g. "png", "pdf" or "txt"
+ * the file itself in the payload
+### Example:
+
+ curl -F "data=@test.txt" https://localhost:9980/lool/convert-to/docx > out.docx
+
+ * or in HTML:
+```html
+<form action="https://localhost:9980/lool/convert-to/docx" enctype="multipart/form-data" method="post">
+ File: <input type="file" name="data"><br/>
+ <input type="submit" value="Convert to DOCX">
+</form>
+```
+
+Alternatively you can omit the `<format>`, and instead provide it as another parameter
+### Example:
+
+ curl -F "data=@test.odt" -F "format=pdf" https://localhost:9980/lool/convert-to > out.pdf
+
+* or in HTML:
+```html
+<form action="https://localhost:9980/lool/convert-to" enctype="multipart/form-data" method="post">
+ File: <input type="file" name="data"><br/>
+ Format: <input type="text" name="format"><br/>
+ <input type="submit" value="Convert">
+</form>
+```
+
+WOPI Extensions
+===============
+
+LibreOffice Online uses a WOPI-like protocol to interact with hosts who want to integrate LibreOffice Online in them.
+
+Refer to [WOPI docs](https://wopi.readthedocs.io/en/latest/) for further details on the protocol's inspiration.
+
+CheckFileInfo response properties
+---------------------------------
+
+### BaseFileName
+A string containing the basename of the file, omitting its path.
+
+### DisablePrint
+Disables print functionality in libreoffice online backend. Ift rue, HidePrintOption is assumed to be true
+
+### OwnerID
+A programmatic string identifier for the owner of the file.
+
+### PostMessageOrigin
+A string for the domain the host page sends/receives PostMessages from, we only listen to messages from this domain.
+
+### Size
+Size of the file in bytes (64bit)
+
+### UserCanWrite
+A boolean flag, indicating whether the user has permission to edit and/or over-write the file. If not set PutFile will fail.
+
+### UserCanNotWriteRelative
+A boolean flag indiciating that the user cannot Save-As on this server, so PutFileRelative will fail.
+
+### UserId
+A programmatic string identifier of the user.
+
+### UserFriendlyName
+A string representing the name of the user for display in the UI.
+
+
+CheckFileInfo extended response properties
+------------------------------------------
+
+### HidePrintOption
+If set to true, hides the print option from the filemenu bar in the UI
+
+### HideSaveOption
+If set to true, hides the save button from the toolbar and file menubar in the UI
+
+### HideExportOption
+Hides 'Download as' option in the file menubar
+
+### DisableExport
+Disables export functionality in backend. If set to true, HideExportOption is assumed to be true
+
+### DisableCopy
+Disables copying from the document in libreoffice online backend. Pasting into the document would still be possible. However, it is still possible to do an "internal" cut/copy/paste.
+
+### DisableInactiveMessages
+Disables displaying of the explanation text on the overlay when the document becomes inactive or killed. With this, the JS integration must provide the user with appropriate message when it gets Session_Closed or User_Idle postMessage's.
+
+### EnableOwnerTermination
+If set to true, it allows the document owner (the one with OwnerId =UserId) to send a 'closedocument' message (see protocol.txt)
+
+### UserExtraInfo
+JSON object that contains additional info about the user, namely the avatar image.
+
+**Example:** 'UserExtraInfo' => [ 'avatar' => 'http://url/to/user/avatar', 'mail' => 'user at server.com' ]
+
+**Note:** There is strict Content Security Policy that restricts image resources (img-src), therefore the avatar URL must not violate the CSP, otherwise it will show as broken images.
+
+### WatermarkText
+If set to a non-empty string, is used for rendering a watermark-like text on each tile of the document
+
+**Note:** It is possible to just hide print, save, export options while still being able to access them from other hosts using PostMessage API (see [loleaflet/reference.html](https://www.collaboraoffice.com/collabora-online-editor-api-reference/))
+
+Alternative authentication possibility
+--------------------------------------
+
+Instead of the 'access_token', it is possible to pass an 'access_header' at the places where the 'access_token' would be used in the initial iframe setup.
+
+The 'access_header' can be eg. of a form
+
+ Authorization: Basic abcd1234==
+
+This header is then used in all the protocol calls like PutFile, GetFile or CheckFileInfo, allowing Basic authentication to work.
+
+PutFile headers
+---------------
+
+PutFile additionally indicates whether the user has modified the document before the save, or if they just pressed the Save button without any modification. The following header:
+
+ X-LOOL-WOPI-IsModifiedByUser
+
+will have the value 'true' or 'false' accordingly.
+
+To distinguish autosave vs. explicit user requests to save, the following header:
+
+ X-LOOL-WOPI-IsAutosave
+
+will have the value 'true' when the PutFile is triggered by autosave, and 'false' when triggered by explicit user operation (Save button or menu entry).
+
+Detecting external document change
+----------------------------------
+
+Locking is omitted from our WOPI-like protocol since it goes against common EFSS solutions usage. Instead, LibreOffice Online uses timestamps to detect document changes.
+
+When the document is updated in your storage while being edited in LibreOffice Online and there are unsaved changes, we detect it as soon as possible and ask the user if he/she would like to overwrite the changes or reload the new document from the storage.
+
+In case there are no unsaved changes, we reload the new document without asking the user.
+
+To support this feature, the host implementation has to specify LastModifiedTime field in both CheckFileInfo and PutFile calls.
+
+Additionally, hosts must check for a header in PutFile response:
+
+ X-LOOL-WOPI-Timestamp
+
+This header contains the ISO8601 round-trip formatted time of file’s last modified time in storage, as known by LibreOffice Online. In case this header is present and its value does not match the file’s modified time in storage, it indicates that document being edited is not the one that is present in the storage.
+
+Hosts should not save the file to storage in such cases and respond with HTTP 409 along with LibreOffice Online specific status code:
+
+ HTTP 409 with JSON:
+ {
+ “LOOLStatusCode”: 1010
+ }
+
+When the user chooses "overwrite" when asked how to resolve the conflict, LibreOffice will attempt one more save operation, but this time it will lack the X-LOOL-WOPI-Timestamp header, which means "save regardless of state of the
+file".
+
diff --git a/wsd/reference.txt b/wsd/reference.txt
deleted file mode 100644
index a05223ca7..000000000
--- a/wsd/reference.txt
+++ /dev/null
@@ -1,192 +0,0 @@
-LibreOffice Online API
-=======================
-
-Document conversion:
- - API: HTTP POST to /lool/convert-to/<format>
- - the format is e.g. "png", "pdf" or "txt"
- - the file itself in the payload
- - example
- - curl -F "data=@test.txt" https://localhost:9980/lool/convert-to/docx > out.docx
- - or in html:
- <form action="https://localhost:9980/lool/convert-to/docx" enctype="multipart/form-data" method="post">
- File: <input type="file" name="data"><br/>
- <input type="submit" value="Convert to DOCX">
- </form>
-
- - alternatively you can omit the <format>, and instead
- provide it as another parameter
- - example
- - curl -F "data=@test.odt" -F "format=pdf" https://localhost:9980/lool/convert-to > out.pdf
- - or in html:
- <form action="https://localhost:9980/lool/convert-to" enctype="multipart/form-data" method="post">
- File: <input type="file" name="data"><br/>
- Format: <input type="text" name="format"><br/>
- <input type="submit" value="Convert">
- </form>
-
-WOPI Extensions
-===============
-
-LibreOffice Online uses a WOPI-like protocol to interact with hosts who
-want to integrate LibreOffice Online in them.
-
-Refer to WOPI docs[https://wopi.readthedocs.io/en/latest/] for further
-details on the protocol's inspiration.
-
-CheckFileInfo response properties
-----------------------------------
-
-BaseFileName
- A string containing the basename of the file, omitting its path.
-
-DisablePrint
- Disables print functionality in libreoffice online backend. If
- true, HidePrintOption is assumed to be true
-
-OwnerID
- A programmatic string identifier for the owner of the file.
-
-PostMessageOrigin
- A string for the domain the host page sends/receives
- PostMessages from, we only listen to messages from this domain.
-
-Size
- Size of the file in bytes (64bit)
-
-UserCanWrite
- A boolean flag, indicating whether the user has permission
- to edit and/or over-write the file. If not set PutFile will fail.
-
-UserCanNotWriteRelative
- A boolean flag indiciating that the user cannot Save-As on
- this server, so PutFileRelative will fail.
-
-UserId
- A programmatic string identifier of the user.
-
-UserFriendlyName
- A string representing the name of the user for display in the UI.
-
-
-CheckFileInfo extended response properties
-------------------------------------------
-
-HidePrintOption
- If set to true, hides the print option from the filemenu bar in the UI
-
-HideSaveOption
- If set to true, hides the save button from the toolbar and file menubar
- in the UI
-
-HideExportOption
- Hides 'Download as' option in the file menubar
-
-DisableExport
- Disables export functionality in backend. If set to true,
- HideExportOption is assumed to be true
-
-DisableCopy
- Disables copying from the document in libreoffice online
- backend. Pasting into the document would still be possible.
- However, it is still possible to do an "internal" cut/copy/paste.
-
-DisableInactiveMessages
- Disables displaying of the explanation text on the overlay when the
- document becomes inactive or killed. With this, the JS integration
- must provide the user with appropriate message when it gets
- Session_Closed or User_Idle postMessage's.
-
-EnableOwnerTermination
- If set to true, it allows the document owner (the one with OwnerId =
- UserId) to send a 'closedocument' message (see protocol.txt)
-
-UserExtraInfo
- JSON object that contains additional info about the user, namely the
- avatar image.
-
- Example: 'UserExtraInfo' => [ 'avatar' => 'http://url/to/user/avatar', 'mail' => 'user at server.com' ]
-
- Note: There is strict Content Security Policy that restricts image
- resources (img-src), therefore the avatar URL must not violate the
- CSP, otherwise it will show as broken images.
-
-WatermarkText
- If set to a non-empty string, is used for rendering a watermark-like
- text on each tile of the document
-
-Note that it is possible to just hide print, save, export options
-while still being able to access them from other hosts using
-PostMessage API (see loleaflet/reference.html)
-
-Alternative authentication possibility
---------------------------------------
-
-Instead of the 'access_token', it is possible to pass an 'access_header' at
-the places where the 'access_token' would be used in the initial iframe setup.
-
-The 'access_header' can be eg. of a form
-
- Authorization: Basic abcd1234==
-
-This header is then used in all the protocol calls like PutFile,
-GetFile or CheckFileInfo, allowing Basic authentication to work.
-
-PutFile headers
----------------
-
-PutFile additionally indicates whether the user has modified the document
-before the save, or if they just pressed the Save button without any
-modification. The following header:
-
- X-LOOL-WOPI-IsModifiedByUser
-
-will have the value 'true' or 'false' accordingly.
-
-To distinguish autosave vs. explicit user requests to save, the following
-header:
-
- X-LOOL-WOPI-IsAutosave
-
-will have the value 'true' when the PutFile is triggered by autosave, and
-'false' when triggered by explicit user operation (Save button or menu entry).
-
-Detecting external document change
-----------------------------------
-
-Locking is omitted from our WOPI-like protocol since it goes against
-common EFSS solutions usage. Instead, LibreOffice Online uses
-timestamps to detect document changes.
-
-When the document is updated in your storage while being edited in
-LibreOffice Online and there are unsaved changes, we detect it as soon
-as possible and ask the user if he/she would like to overwrite the
-changes or reload the new document from the storage.
-
-In case there are no unsaved changes, we reload the new document without
-asking the user.
-
-To support this feature, the host implementation has to specify
-LastModifiedTime field in both CheckFileInfo and PutFile calls.
-
-Additionally, hosts must check for a header in PutFile response:
-
- X-LOOL-WOPI-Timestamp
-
-This header contains the ISO8601 round-trip formatted time of file’s last
-modified time in storage, as known by LibreOffice Online. In case this header
-is present and its value does not match the file’s modified time in storage,
-it indicates that document being edited is not the one that is present in the
-storage.
-
-Hosts should not save the file to storage in such cases and respond with
-HTTP 409 along with LibreOffice Online specific status code:
-
- HTTP 409 with JSON:
- {
- “LOOLStatusCode”: 1010
- }
-
-When the user chooses "overwrite" when asked how to resolve the conflict,
-LibreOffice will attempt one more save operation, but this time it will lack
-the X-LOOL-WOPI-Timestamp header, which means "save regardless of state of the
-file".
More information about the Libreoffice-commits
mailing list