From a41b8a8b8f012693a98809785df7ecc3a3d1d2f3 Mon Sep 17 00:00:00 2001 From: Jonas Date: Wed, 17 Jul 2024 15:41:08 +0200 Subject: [PATCH] feat(developers): Document public reference API Signed-off-by: Jonas --- developer_manual/digging_deeper/reference.rst | 45 ++++++++++++++++--- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/developer_manual/digging_deeper/reference.rst b/developer_manual/digging_deeper/reference.rst index d23cbad796c..1bd230e5cbf 100644 --- a/developer_manual/digging_deeper/reference.rst +++ b/developer_manual/digging_deeper/reference.rst @@ -126,11 +126,18 @@ Accessing the API directly can be useful if you want to: Endpoints to resolve links: -* GET /ocs/v2.php/references/resolve - * ``reference`` parameter which is the link to resolve -* GET /ocs/v2.php/references/resolve - * ``references`` parameter which is an array of links to resolve - * ``limit`` parameter which is the maximum number of links to resolve +* GET /ocs/v2.php/references/resolve (authenticated) + * ``reference`` parameter with the link to resolve +* GET /ocs/v2.php/references/resolvePublic + * ``reference`` parameter with the link to resolve + * ``sharingToken`` parameter with the public share token +* POST /ocs/v2.php/references/resolve + * ``references`` parameter with an array of links to resolve + * ``limit`` parameter with the maximum number of links to resolve +* POST /ocs/v2.php/references/resolve + * ``references`` parameter with an array of links to resolve + * ``sharingToken`` parameter with the public share token + * ``limit`` parameter with the maximum number of links to resolve Request examples ^^^^^^^^^^^^^^^^ @@ -462,8 +469,12 @@ A reference provider is a class implementing the ``OCP\Collaboration\Reference\I If you just want to resolve links, simply implement the ``IReferenceProvider`` interface. This is described in the "Resolving links" section. +To support resolving links from public shares, the ``OCP\Collaboration\Reference\IPublicReferenceProvider`` interface +needs to be implemented as well. + If you want your reference provider to be used by the Smart Picker, you need to extend the ``OCP\Collaboration\Reference\ADiscoverableReferenceProvider`` class to declare all required information. + There are 2 ways to make your provider appear in the smart picker, in other words, 2 types of providers: * Either your reference provider implements the ``OCP\Collaboration\Reference\ISearchableReferenceProvider`` interface and you declare a list of unified search providers that will be used by the Smart Picker @@ -478,8 +489,11 @@ Links that are not matched by any reference provider will always be handled by t This provider will try to get the information declared in the target page's meta tag. The link preview will be rendered with the default widget. -For your provider to properly handle some links, -you need to implement the ``matchReference`` and ``resolve`` methods of ``IReferenceProvider``. +For your provider to properly handle some links, you need to implement the ``matchReference`` and ``resolve`` +methods of ``IReferenceProvider``. + +In order to resolve links from a public share, ``resolvePublic`` from ``IPublicReferenceProvider`` has to be implemented +additionally. Match links ~~~~~~~~~~~ @@ -499,6 +513,9 @@ Resolving links The ``resolve`` method of ``IReferenceProvider`` is used to get information about a link and return it as a ``OCP\Collaboration\Reference\Reference`` object. +Respectively the ``resolvePublic`` method of ``IPublicReferenceProvider`` is used to get information about a +link from a public share (available since Nextcloud 30). + Using the default widget ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -522,6 +539,13 @@ then you just need to provide a title, a description and optionally an image. return null; } + public function resolveReferencePublic(string $referenceText, string $shareToken): ?IReference { + if ($this->checkShareToken() === $shareToken) { + return $this->resolveReference($referenceText); + } + return null; + } + Using custom reference widgets ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -563,6 +587,13 @@ This way we make sure any generic rendering of link previews still shows some in return null; } + public function resolveReferencePublic(string $referenceText, string $shareToken): ?IReference { + if ($this->checkShareToken() === $shareToken) { + return $this->resolveReference($referenceText); + } + return null; + } + On the frontend side you need to implement and register your custom component. Here is a component example: You need to react to the ``OCP\Collaboration\Reference\RenderReferenceEvent``