Add documentation

Signed-off-by: Julius Härtl <jus@bitgrid.net>

1 files changed, 120 insertions, 0 deletions

diff --git a/docs/frontend-integration.md b/docs/frontend-integration.md
new file mode 100644
index 00000000..bab1782a
--- /dev/null
+++ b/docs/frontend-integration.md
@@ -0,0 +1,120 @@
+## Frontend integration API
+
+### Configuration
+
+The Collabora configuration for creating new files with their mietype and extension per file type is exposed to `OCA.RichDocuments.config.create`.
+
+```json
+{
+  "create": {
+    "document": {
+      "extension": "odt",
+      "mime": "application/vnd.oasis.opendocument.text"
+    },
+    "spreadsheet": {
+      "extension": "ods",
+      "mime": "application/vnd.oasis.opendocument.spreadsheet"
+    },
+    "presentation": {
+      "extension": "odp",
+      "mime": "application/vnd.oasis.opendocument.presentation"
+    }
+  }
+}
+```
+
+### Open viewer
+
+
+The following two methods are exposed in order to manually trigger the Collabora viewer opening a file:
+
+#### Open an existing file
+
+`OCA.RichDocuments.open(params)` will open the Collabora view for an existing file.
+
+Params requires the following properties:
+- fileId: (string) internal file id
+- path: (string) full path to the file
+- shareOwnerId: (string) uid of share owner for shared files
+- fileList: (object) optional file list object (see limitations below when not passing it)
+
+
+```javascript
+OCA.RichDocuments.open({
+	fileId: 1234,
+	path: '/path/to/file.odt',
+	shareOwnerId: 'admin@nextcloud',
+    fileList: FileList
+})
+```
+
+#### Create a new file from a template
+
+`OCA.RichDocuments.openWithTemplate(params)` provides a method to open a Collabora view for a file that should be created from a template. Calling this method requires the file to be already present on the filesytem and shown in the file list.
+
+Params requires the following properties:
+- fileId: (string) internal file id
+- path: (string) full path to the file
+- shareOwnerId: (string) uid of share owner for shared files
+- fileList: (object) optional file list object (see limitations below when not passing it)
+- templateId: (string) file id of the template
+
+```javascript
+OCA.RichDocuments.openWithTemplate({
+	fileId: -1,
+	path: '/path/to/file.odt,
+	templateId: templateId
+})
+```
+
+### Handlers
+
+Handlers provide a way to hook into the files app integration in order to inject custom behaviour during certain actions.
+
+The return value indicates if the default behavour should be blocked (true) or still be executed (false).
+
+The following handlers are currently supported:
+
+- initAfterReady: will be called once the Collabora frame has been loaded
+- close: will be called after the Collabora view has been closed
+- share: will be called before the default share action is triggered
+- rename: will be called before the default rename action is triggered (the new filename is available as a property of the filesAppIntegration parameter)
+- showRevHistory: will be called before the default show revision history action is triggered
+
+The filesAppIntegration parameter can be used to extract the current context of the edited file. The following properties are available for that:
+- fileName
+- fileId
+
+The following code shows an example on how to register the different handlers:
+
+```javascript
+(function() {
+
+	OCA.RichDocuments.FilesAppIntegration.registerHandler('initAfterReady', (filesAppIntegration) => {
+		console.debug('called initAfterReady', filesAppIntegration)
+		return false
+	})
+
+	OCA.RichDocuments.FilesAppIntegration.registerHandler('close', (filesAppIntegration) => {
+		console.debug('called close', filesAppIntegration)
+		return false
+	})
+
+	OCA.RichDocuments.FilesAppIntegration.registerHandler('share', (filesAppIntegration) => {
+		console.debug('called share', filesAppIntegration)
+		return false
+	})
+
+	OCA.RichDocuments.FilesAppIntegration.registerHandler('rename', (filesAppIntegration) => {
+		console.debug('called rename', filesAppIntegration)
+		return false
+	})
+
+
+	OCA.RichDocuments.FilesAppIntegration.registerHandler('showRevHistory', (filesAppIntegration) => {
+		console.debug('called showRevHistory', filesAppIntegration)
+		return false
+	})
+
+})()
+```