richdocuments/docs/frontend-integration.md at main

mirror of https://github.com/nextcloud/richdocuments.git synced 2025-12-17 21:12:14 +01:00

Mike Kaganski 68ebfaa526 Implement support for insertion of multimedia from Nextcloud assets

This change adds ability to insert multimedia files from Nextcloud
to Impress documents. It advertises EnableInsertRemoteFile capability,
so that Office activates the feature (depends on Office including
commit 60d9a9c20bf69b3f1d8591b2d8400c4a453970ab - older builds won't
show the respective button).

Signed-off-by: Mike Kaganski <mike.kaganski@collabora.com>

2024-11-19 18:05:48 +05:00

8.6 KiB

Raw Permalink Blame History

Frontend integration API

Configuration

The Nextcloud Office configuration for creating new files with their mimetype and extension per file type is exposed to OCA.RichDocuments.config.create.

{
  "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 Nextcloud Office 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
fileModel: (OCA.Files.FileInfoModel) model of the file that will be opened
fileList: (object) optional file list object

OCA.RichDocuments.open({
	fileId: 1234,
	path: '/path/to/file.odt',
	fileModel: new OCA.Files.FileInfoModel({...})
    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
templateId: (string) file id of the template
fileModel: (OCA.Files.FileInfoModel) model of the file that will be opened
fileList: (object) optional file list object

OCA.RichDocuments.openWithTemplate({
	fileId: -1,
	path: '/path/to/file.odt,
	templateId: templateId,
    fileModel: new OCA.Files.FileInfoModel({...})
})

Changes to the fileModel should be propagated by triggering a backbone change event:

window.OCA.RichDocuments.FilesAppIntegration.registerHandler('actionFavorite', (filesAppIntegration) => {
    // custom logic here
    // make sure to trigger a change on the file info model object like this:
    filesAppIntegration.getFileModel().trigger('change', newFileModel)
    return true
})

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
saveAs: will be called on a save_as response by Collabora
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
insertGraphic: will be called when an image from the Nextcloud storage should be inserted
- Arguments
  - insertFileFromPath(path): Callback to trigger the actual inserting of the graphic from an absolute file path
insertFile: will be called when a file (e.g., multimedia) from the Nextcloud storage should be inserted (generalized insertGraphic)
- Arguments
  - mimeTypeFilter: array of MIME types (strings) to filter in the UI
  - insertFileFromPath(path): Callback to trigger the actual inserting of the file from an absolute file path

In addition, the following handlers can be used to overwrite the handling of file actions that are rendered in the Nextcloud header bar:

actionDetails
actionDownload
actionFavorite

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 callback function of each handler will be called with the following parameters:

filesAppIntegration: current instance of the filesAppIntegration object
arguments (optional): see list of supported handlers for details

The following code shows an example on how to register the different handlers:

(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
	})

    OCA.RichDocuments.FilesAppIntegration.registerHandler('insertGraphic', (filesAppIntegration, { insertFileFromPath }) => {
        const path = prompt('Enter a file path', '')
        insertFileFromPath(path)
        return true
    })

})()

Events

Events are emitted through the @nextcloud/event-bus for the different document loading states.

Files app scope

When Collabora files are opened through the files app integration (either in the files app or on public share pages), the following events will be emitted to be able to track document opening progress and its success or failure state.

subscribe('richdocuments:file-open:started', data => console.error('richdocuments:file-open:started', data))
subscribe('richdocuments:file-open:succeeded', data => console.error('richdocuments:file-open:succeeded', data))
subscribe('richdocuments:file-open:failed', data => console.error('richdocuments:file-open:failed', data))

Event names:

richdocuments:file-open:started
richdocuments:file-open:succeeded
richdocuments:file-open:failed

Data properties:

currentUser (string|null): user id of the currently logged-in user
file (object)
- fileId (integer|undefined): undefined for single public shares, otherwise the file id is available
- filePath (string): "/testfile.odt"
- sharingToken (string|undefined): Optional sharing token when opened on a public share link
reason (string): Only for a failed event, timeout|collabora
collaboraResponse (object); Optional when reason is collabora

Example succeeded event data:

{
  "currentUser": "admin",
  "file": {
    "fileId": "204",
    "filePath": "/test.odt",
    "sharingToken": undefined
  }
}

Example failed event data:

{
  "reason": "collabora",
  "collaboraResponse": "WOPI::GetFile failed: []",
  "currentUser": "admin",
  "file": {
    "fileId": "204",
    "filePath": "/test.odt",
    "sharingToken": undefined
  }
}

Document scope

The event in the document scope is also emitted on direct editing through mobile apps, as there the files app integration is not available.

subscribe('richdocuments:wopi-load:started', data => console.error('richdocuments:wopi-load:started', data))
subscribe('richdocuments:wopi-load:succeeded', data => console.error('richdocuments:wopi-load:succeeded', data))
subscribe('richdocuments:wopi-load:failed', data => console.error('richdocuments:wopi-load:failed', data))