1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
## 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
- fileModel: (OCA.Files.FileInfoModel) model of the file that will be opened
- fileList: (object) optional file list object
```javascript
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
```javascript
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:
```javascript
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
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:
```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
})
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))
```
Event names:
- richdocuments:wopi-load:started
- richdocuments:wopi-load:succeeded
- richdocuments:wopi-load:failed
Data properties:
- wopiFileId (string): file id constructed to be used by Collabora for the WOPI access
- reason (string): Only for a failed event, timeout|collabora
- collaboraResponse (string): Optional when failure reason is collabora
Example failed event data:
```
{
"reason": "collabora",
"collaboraResponse": "WOPI::GetFile failed: []",
"wopiFileId": "288_oct9lk1km6wy"
}
```
|
