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 ------------------------------------