From 52408a7e5402347fbc33a4a99991462eb37d6054 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 9 Sep 2026 13:18:54 +0200 Subject: [PATCH] docs(dev): the viewer is a library, not an app The viewer app is gone from Nextcloud 36 and ships as @nextcloud/viewer. The manual still documented the app's own API: the LoadViewer event apps dispatched to ask it to load itself, and a development setup that cloned its repository, which is no longer needed now that every alwaysEnabled app lives in the server tree. The release notes gain what an app has to change: registering a handler, opening the viewer through getViewer() rather than OCA.Viewer, and the enabled preview providers, which moved from an initial state the app provided to core.previews.enabled_providers, documented with the other capabilities. Assisted-by: ClaudeCode:claude-opus-5 Signed-off-by: skjnldsv --- developer_manual/basics/events.rst | 7 -- .../client_apis/OCS/ocs-api-overview.rst | 30 ++++++++ developer_manual/getting_started/devenv.rst | 17 ----- .../release_notes/critical_changes.rst | 76 +++++++++++++++++++ 4 files changed, 106 insertions(+), 24 deletions(-) diff --git a/developer_manual/basics/events.rst b/developer_manual/basics/events.rst index 9df58b82689..287f840c33e 100644 --- a/developer_manual/basics/events.rst +++ b/developer_manual/basics/events.rst @@ -384,13 +384,6 @@ This event is triggered right after the LDAP group backend is registered. This event is triggered right after the LDAP user backend is registered. -``\OCA\Viewer\Event\LoadViewer`` -******************************** - -.. versionadded:: 17 - -This event is triggered whenever the viewer is loaded and extensions should be loaded. - .. include:: _available_events_ocp.rst Hooks diff --git a/developer_manual/client_apis/OCS/ocs-api-overview.rst b/developer_manual/client_apis/OCS/ocs-api-overview.rst index 6eb2697fc10..c8d5d7902da 100644 --- a/developer_manual/client_apis/OCS/ocs-api-overview.rst +++ b/developer_manual/client_apis/OCS/ocs-api-overview.rst @@ -179,6 +179,36 @@ Clients can obtain capabilities provided by the Nextcloud server and its apps vi +.. _preview-capabilities: + +Preview capabilities +-------------------- + +.. versionadded:: 36 + +The mime types the server can render a preview for. A client uses it to tell the formats a +browser cannot display on its own, but the server can render, from the ones it can do neither +of: ``image/heic``, ``image/heif`` and ``image/tiff`` are viewable through a preview and not +otherwise. + +Each entry is the mime pattern a provider registered itself for, as a regular expression +delimited by slashes. The list is empty when previews are turned off entirely +(``enable_previews``), which means no preview can be requested for any file. + +.. code:: json + + { + "core": { + "previews": { + "enabled_providers": [ + "/image\\/png/", + "/image\\/jpeg/", + "/image\\/hei(f|c)/" + ] + } + } + } + Theming capabilities -------------------- diff --git a/developer_manual/getting_started/devenv.rst b/developer_manual/getting_started/devenv.rst index dafcc33be8e..15811ec31bb 100644 --- a/developer_manual/getting_started/devenv.rst +++ b/developer_manual/getting_started/devenv.rst @@ -87,23 +87,6 @@ or:: Now access the installation at http://localhost/ (or the corresponding URL) in your web browser to set up your instance. -Check out external shipped apps -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This optional step is especially necessary if you want to test upgrading, as the following apps are required to be present during an upgrade. - -Install the viewer app:: - - cd /var/www/apps - git clone https://github.com/nextcloud/viewer.git - -Make sure to use a version compatible with the server by checking out the matching tag. -You can check the ``appinfo/info.xml`` of the app to see if its ``min-version`` field is compatible with the current server. - -When upgrading the server code you might need to upgrade the app code as well before running ``occ upgrade``. - -.. note:: The same applies to all the apps listed under ``alwaysEnabled`` in `shipped.json `_ but most are already present in the server repository. - .. _debugmode: Enabling debug mode diff --git a/developer_manual/release_notes/critical_changes.rst b/developer_manual/release_notes/critical_changes.rst index be8351a0e14..c9ca28a0b54 100644 --- a/developer_manual/release_notes/critical_changes.rst +++ b/developer_manual/release_notes/critical_changes.rst @@ -89,6 +89,82 @@ Make sure to adjust your CI matrix for testing with them. This is automatically .. note:: MySQL 9+ deprecated support for MD5, so we strongly recommend to migrate away from the MD5 SQL function in your apps. +The Viewer is a library, not an app +----------------------------------- + +The ``viewer`` app has been removed from Nextcloud 36. The viewer itself now ships as the +`@nextcloud/viewer `_ library, which any app +can depend on: + +.. code-block:: bash + + npm install --save @nextcloud/viewer + +Importing it registers the handlers for images, video and audio, and offers this copy of the +viewer to the page. Several apps on one page may each bring their own copy: they elect the +newest between them, and only that one is ever loaded, the first time a file is opened. + +Registering a handler +^^^^^^^^^^^^^^^^^^^^^ + +Register handlers from a script loaded with ``\OCP\Util::addInitScript()``. The Files list +reads the available actions when it first renders, so a handler registered after that is a +file that does not open. + +.. code-block:: javascript + + import { registerHandler } from '@nextcloud/viewer' + + registerHandler({ + id: 'my-app', + displayName: t('my_app', 'My files'), + // A custom element you define yourself, and which receives the file to show + tagname: 'my-app-viewer', + enabled: (nodes) => nodes.every((node) => node.mime === 'application/x-my-format'), + }) + +Opening the viewer +^^^^^^^^^^^^^^^^^^ + +``OCA.Viewer`` is gone, along with the ``\OCA\Viewer\Event\LoadViewer`` event apps +dispatched to ask the app to load itself. Nothing needs to be dispatched any more; ask the +service for the viewer and hand it nodes: + +.. code-block:: javascript + + import { canView, getViewer } from '@nextcloud/viewer' + + // OCA.Viewer.open({ path }) becomes, with `node` an INode from @nextcloud/files: + getViewer().open([node], node) + + // OCA.Viewer.mimetypes.includes(node.mime) becomes: + canView(node) + +The first argument is the list to page through, the second the file to open. ``compare(a, b)`` +replaces ``OCA.Viewer.compare()``, and ``open()`` takes options as a third argument, among them +``enableSidebar`` for a file the Files sidebar cannot resolve. + +``OCA.Viewer.setRootElement()`` has no replacement. It rendered a single file into an element +of your choosing instead of the modal, and the only known user was a public share page. Show a +preview of the file there and let a click on it call ``open()``. + +The full handler API is documented with the library. + +Enabled preview providers +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The viewer app provided the enabled preview providers as an initial state, which apps could +read with ``loadState('viewer', 'enabled_preview_providers')``. It is a capability now, so it +is available wherever capabilities are, public share pages included: + +.. code-block:: javascript + + import { getCapabilities } from '@nextcloud/capabilities' + + getCapabilities().core.previews.enabled_providers + +See :ref:`preview-capabilities` for what it contains. + Removed front-end APIs and libraries ------------------------------------