libreoffice-online/wsd/reference.txt

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 WOPI protocol to interact with hosts who wants to
integrate LibreOffice Online in them.

Refer to WOPI docs[https://wopi.readthedocs.io/en/latest/] for detailed
information. This documentation only mentions extensions to upstream WOPI protocol,
WOPI extensions, that are implemented by LibreOffice Online backend in addition to
upstream WOPI protocol.

(Please note that upstream WOPI implementation is also not 100% complete)

CheckFileInfo 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

DisablePrint
	Disables print functionality in libreoffice online backend. If true,
	HidePrintOption is assumed to be true

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@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 WOPI 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 WOPI 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).