Merge pull request #2958 from nextcloud/backport/2922/stable31

susnux · web-flow · commit bfc9af1b5068 · 2025-09-02T19:30:17.000+02:00
[stable31] feat: add API package to register handlers in init scripts
diff --git a/README.md b/README.md
@@ -146,6 +146,46 @@ OCA.Viewer.close()
 ```
 
 ### 🔍 Add you own file view
+
+If you want to make your app compatible with this app, you can use the methods provided by the [`@nextcloud/viewer`](https://www.npmjs.com/package/@nextcloud/viewer) npm.js package:
+1. Create a vue component which use the `path` and `mime` props (they will be automatically passed by the viewer)
+2. Register your mime viewer with the following:
+   ``` js
+    import { registerHandler } from '@nextcloud/viewer'
+    import VideoView from 'VideoView.vue'
+
+    registerHandler({
+        // unique id
+        id: 'video',
+
+       // optional, it will group every view of this group and
+       // use the proper view when building the file list
+       // of the slideshow.
+       // e.g. you open an image/jpeg that have the `media` group
+       // you will be able to see the video/mpeg from the `video` handler
+       // files that also have the `media` group set.
+       group: 'media',
+
+       // the list of mimes your component is able to display
+       mimes: [
+            'video/mpeg',
+            'video/ogg',
+            'video/webm',
+            'video/mp4'
+        ],
+
+        // your vue component view
+        component: VideoView
+    })
+   ```
+3. Make sure your script is loaded with `\OCP\Util::addInitScript` so that the handler is registered **before** the viewer is loaded.
+4. if you feel like your mime should be integrated on this repo, you can also create a pull request with your object on the `models` directory and the view on the `components` directory. Please have a look at what's already here and take example of it. 🙇‍♀️
+
+
+### Legacy handler registration
+> [!CAUTION]
+> Using OCA.Viewer for registering your handlers is not recommended as this might break depending on the script loading order
+
 If you want to make your app compatible with this app, you can use the `OCA.Viewer` methods
 1. Create a vue component which use the `path` and `mime` props (they will be automatically passed by the viewer)
 2. Register your mime viewer with the following:
@@ -176,4 +216,4 @@ If you want to make your app compatible with this app, you can use the `OCA.View
         component: VideoView
     })
    ```
-3. if you feel like your mime should be integrated on this repo, you can also create a pull request with your object on the `models` directory and the view on the `components` directory. Please have a look at what's already here and take example of it. 🙇‍♀️
+3. Make sure your script is loaded with `\OCP\Util::addScript` (in contrast to using the API package)!
diff --git a/css/main-C3PMk74T.chunk.css b/css/main-C3PMk74T.chunk.css
diff --git a/css/viewer-main.css b/css/viewer-main.css
@@ -1,3 +1,3 @@
 /* extracted by css-entry-points-plugin */
-@import './main-zfQgoLdI.chunk.css';
+@import './main-C3PMk74T.chunk.css';
 @import './viewerAction-ziP2nhPq.chunk.css';
diff --git a/js/viewer-main.mjs b/js/viewer-main.mjs
diff --git a/js/viewer-main.mjs.map b/js/viewer-main.mjs.map
diff --git a/package-lock.json b/package-lock.json
diff --git a/src/api_package/.gitignore b/src/api_package/.gitignore
@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+/dist
+/package-lock.json
diff --git a/src/api_package/README.md b/src/api_package/README.md
@@ -0,0 +1,47 @@
+<!--
+  - SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+# Nextcloud Viewer integration
+
+[![REUSE status](https://api.reuse.software/badge/github.com/nextcloud/viewer)](https://api.reuse.software/info/github.com/nextcloud/viewer)
+
+
+## Usage
+### 🔍 Add you own file view
+
+If you want to make your app compatible with this app, you can use the methods provided by the [`@nextcloud/viewer`](https://www.npmjs.com/package/@nextcloud/viewer) npm.js package:
+1. Create a vue component which use the `path` and `mime` props (they will be automatically passed by the viewer)
+2. Register your mime viewer with the following:
+   ``` js
+    import { registerHandler } from '@nextcloud/viewer'
+    import VideoView from 'VideoView.vue'
+
+    registerHandler({
+        // unique id
+        id: 'video',
+
+       // optional, it will group every view of this group and
+       // use the proper view when building the file list
+       // of the slideshow.
+       // e.g. you open an image/jpeg that have the `media` group
+       // you will be able to see the video/mpeg from the `video` handler
+       // files that also have the `media` group set.
+       group: 'media',
+
+       // the list of mimes your component is able to display
+       mimes: [
+            'video/mpeg',
+            'video/ogg',
+            'video/webm',
+            'video/mp4'
+        ],
+
+        // your vue component view
+        component: VideoView
+    })
+   ```
+3. Make sure your script is loaded with `\OCP\Util::addInitScript` so that the handler is registered **before** the viewer is loaded.
+
+> [!TIP]
+> If you feel like your mime should be integrated on this repo, you can also create a pull request with your object on the `models` directory and the view on the `components` directory. Please have a look at what's already here and take example of it. 🙇‍♀️
diff --git a/src/api_package/REUSE.toml b/src/api_package/REUSE.toml
@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+version = 1
+SPDX-PackageName = "@nextcloud/viewer"
+SPDX-PackageSupplier = "2025 Nextcloud GmbH and Nextcloud contributors"
+SPDX-PackageDownloadLocation = "https://github.com/nextcloud/viewer"
+
+[[annotations]]
+path = ["package.json", "tsconfig.json"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2025 Nextcloud GmbH and Nextcloud contributors"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
diff --git a/src/api_package/global.d.ts b/src/api_package/global.d.ts
@@ -0,0 +1,16 @@
+/*!
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ */
+
+import type { IHandler } from './index.ts'
+
+declare global {
+	interface Window {
+		/**
+		 * Registered viewer handlers.
+		 */
+		// eslint-disable-next-line camelcase
+		_oca_viewer_handlers: Map<string, IHandler>
+	}
+}
diff --git a/src/api_package/index.ts b/src/api_package/index.ts
@@ -0,0 +1,87 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import type { AsyncComponent, Component } from 'vue'
+
+export interface IHandler {
+	/**
+	 * Unique identifier for the handler
+	 */
+	id: string
+
+	/**
+	 * Indicate support for comparing two files
+	 */
+	canCompare?: boolean
+
+	/**
+	 * Vue 2 component to render the file.
+	 */
+	component: Component | AsyncComponent
+
+	/**
+	 * Group identifier to combine for navigating to the next/previous files
+	 */
+	group?: string
+
+	/**
+	 * List of mime types that are supported for opening
+	 */
+	mimes?: string[]
+
+	/**
+	 * Aliases for mime types, used to map different mime types to the same handler.
+	 */
+	mimesAliases?: Record<string, string>
+
+	/**
+	 * Viewer modal theme (one of 'dark', 'light', 'default')
+	 */
+	theme?: 'dark' | 'light' | 'default'
+}
+
+/**
+ * Register a new handler for the viewer.
+ * This needs to be called before the viewer is initialized to ensure the handler is available.
+ * So this should be called from an initialization script (`OCP\Util::addInitScript`).
+ *
+ * @param handler - The handler to register
+ * @throws Error if the handler is invalid
+ */
+export function registerHandler(handler: IHandler): void {
+	validateHandler(handler)
+
+	window._oca_viewer_handlers ??= new Map<string, IHandler>()
+	if (window._oca_viewer_handlers.has(handler.id)) {
+		console.warn(`Handler with id ${handler.id} is already registered.`)
+		return
+	}
+
+	window._oca_viewer_handlers.set(handler.id, handler)
+}
+
+/**
+ * Validate the handler object.
+ *
+ * @param handler - The handler to validate
+ */
+function validateHandler(handler: IHandler) {
+	const { id, mimes, mimesAliases, component } = handler
+
+	// checking valid handler id
+	if (!id || id.trim() === '' || typeof id !== 'string') {
+		throw new Error('The handler does not have a valid id')
+	}
+
+	// Nothing available to process! Failure
+	if ((!mimes || !Array.isArray(mimes)) && !mimesAliases) {
+		throw new Error('Handler needs a valid mime array or mimesAliases')
+	}
+
+	// checking valid handler component data
+	if ((!component || (typeof component !== 'object' && typeof component !== 'function'))) {
+		throw new Error('The handler does not have a valid component')
+	}
+}
diff --git a/src/api_package/package.json b/src/api_package/package.json
@@ -0,0 +1,35 @@
+{
+	"name": "@nextcloud/viewer",
+	"version": "1.0.0",
+	"description": "Nextcloud viewer app API bindings",
+	"keywords": [
+		"nextcloud",
+		"viewer",
+		"api"
+	],
+	"homepage": "https://github.com/nextcloud/viewer",
+	"bugs": {
+		"url": "https://github.com/nextcloud/viewer/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nextcloud/viewer.git"
+	},
+	"license": "AGPL-3.0-or-later",
+	"author": "Nextcloud GmbH and Nextcloud contributors",
+	"type": "module",
+	"exports": {
+		"types": "./dist/index.d.ts",
+		"default": "./dist/index.js"
+	},
+	"main": "dist/index.js",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc"
+	},
+	"peerDependencies": {
+		"vue": "^2.7.16"
+	}
+}
diff --git a/src/api_package/tsconfig.json b/src/api_package/tsconfig.json
@@ -0,0 +1,18 @@
+{
+	"include": ["index.ts", "global.d.ts"],
+	"compilerOptions": {
+		"lib": [
+			"DOM",
+			"ES2020"
+		],
+		"outDir": "dist",
+		"strict": true,
+		"declaration": true,
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"target": "ES2020",
+		"allowImportingTsExtensions": true,
+		"erasableSyntaxOnly": true,
+		"rewriteRelativeImportExtensions": true
+	},
+}
diff --git a/src/views/Viewer.vue b/src/views/Viewer.vue
@@ -528,6 +528,13 @@ export default defineComponent({
 
 		// register on load
 		document.addEventListener('DOMContentLoaded', () => {
+			// load all init handlers
+			if (window._oca_viewer_handlers) {
+				window._oca_viewer_handlers.forEach((handler) => {
+					OCA.Viewer.registerHandler(handler)
+				})
+			}
+
 			// register all primary components mimes
 			this.handlers.forEach(handler => {
 				this.registerHandler(handler)
diff --git a/stylelint.config.cjs b/stylelint.config.cjs
diff --git a/stylelint.config.js b/stylelint.config.js
@@ -0,0 +1,14 @@
+/*!
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+export default {
+	extends: [
+		'@nextcloud/stylelint-config',
+	],
+	ignoreFiles: '!**/*.{vue,css,scss}',
+	rules: {
+		'no-invalid-position-at-import-rule': null,
+	},
+}
