diff options
author | Julius Härtl <jus@bitgrid.net> | 2020-05-18 12:40:16 +0300 |
---|---|---|
committer | Julius Härtl <jus@bitgrid.net> | 2020-10-13 15:35:55 +0300 |
commit | 98038381c09c7bd5ff9e62248f12ebbf1805b35d (patch) | |
tree | 02852eb7148d7af78b95d78fbb2bcaa754c2a302 | |
parent | 790815a9803bc9a9773c034736e1bf8b8d3ec094 (diff) |
Add documentation
Signed-off-by: Julius Härtl <jus@bitgrid.net>
-rw-r--r-- | docs/frontend-integration.md | 120 |
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 + }) + +})() +``` |