From e0bcbfe770cb670bca51cfa73877a826d1edbbd9 Mon Sep 17 00:00:00 2001 From: Benjamin Gaussorgues Date: Fri, 24 Nov 2023 10:58:33 +0100 Subject: [PATCH] Documentation for advanced search Signed-off-by: Benjamin Gaussorgues --- developer_manual/digging_deeper/search.rst | 130 ++++++++++++++++++--- 1 file changed, 115 insertions(+), 15 deletions(-) diff --git a/developer_manual/digging_deeper/search.rst b/developer_manual/digging_deeper/search.rst index b2e22325a..2cadc9d6e 100644 --- a/developer_manual/digging_deeper/search.rst +++ b/developer_manual/digging_deeper/search.rst @@ -14,7 +14,7 @@ The unified search combines a variable number of search providers into a unified Hence the search process consists of two steps. 1. Fetch the current set of search provider IDs - 2. Fetch each provider's search results + 2. Fetch each provider’s search results These two steps have to be run consecutively, but the individual requests in the second step can be dispatched and processed concurrently. @@ -34,19 +34,47 @@ This will return a structure like }, "data": [ { - "id": "mail", - "name": "Mail", - "order": -50 + "id": "talk-message", + "appId": "spreed", + "name": "Messages", + "icon": "/apps/spreed/img/app.svg", + "order": -2, + "triggers": ["talk-message"], + "filters": { + "term": "string", + "since": "datetime", + "until": "datetime", + "person": "person" + }, + "inAppSearch": false }, { "id": "files", - "name": "Files", - "order": 5 + "appId": "files", + "name": "Fichiers", + "icon": "/apps/files/img/app.svg", + "order": 5, + "triggers": ["files"], + "filters": { + "term": "string", + "since": "datetime", + "until": "datetime", + "person": "person", + "min-size": "int", + "max-size": "int", + "mime": "string", + "type": "string" + }, + "inAppSearch": false } ] } } + +``filters`` list filters supported by the provider with their expected type + + Fetching individual search results ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -81,10 +109,10 @@ Fetching individual search results } } -Search providers ----------------- +Simple search providers +----------------------- -A **search provider** is a class the implements the interface ``\OCP\Search\IProvider``. +A **search provider** is a class which implements the interface ``\OCP\Search\IProvider``. .. code-block:: php @@ -109,7 +137,7 @@ A **search provider** is a class the implements the interface ``\OCP\Search\IPro } public function getOrder(string $route, array $routeParameters): int { - if (strpos($route, Application::APP_ID . '.') === 0) { + if (str_contains($route, Application::APP_ID)) { // Active app, prefer my results return -1; } @@ -127,13 +155,78 @@ A **search provider** is a class the implements the interface ``\OCP\Search\IPro } } -The method ``getId`` returns a string identifier of the registered provider. It has to be globally unique, hence must not conflict with any other apps. Therefore it's advised to use just the app ID (e.g. ``mail``) as ID or an ID that is prefixed with the app id, like ``mail_recipients``. ``getName`` is a translated name for your search results. +The method ``getId`` returns a string identifier of the registered provider. It has to be globally unique, hence must not conflict with any other apps. Therefore it’s advised to use just the app ID (e.g. ``mail``) as ID or an ID that is prefixed with the app id, like ``mail_recipients``. ``getName`` is a translated name for your search results. The ``getOrder`` method returns the order of the provider for the current page. With the route parameter you can check if the route is from your app and in that case use a negative value. Otherwise your app should use a value around 50. The method ``search`` transforms a search request into a search result. -The class would typically be saved into a file in ``lib/Search`` of your app but you are free to put it elsewhere as long as it's loadable by Nextcloud's :ref:`dependency injection container`. +The class would typically be saved into a file in ``lib/Search`` of your app but you are free to put it elsewhere as long as it’s loadable by Nextcloud’s :ref:`dependency injection container`. + + +Advanced search provider +------------------------ + +Since Nextcloud 28.0, it is possible to use advanced search providers by implementing ``\OCP\Search\IFilteringProvider``. +This interface allows to supports other filtering types. + +.. code-block:: php + + getFilter('since')?->get(); + /** @var $user ?IUser */ + $user = $query->getFilter('custom_user')?->get(); + + // TODO Do actual search + + return new SearchResult(/* … */); + } + } + +``getSupportedFilters`` lists the filters supported by the provider. If filters send by client are not supported, the provider will not receive the request. + +``getCustomFilters`` allows to declare specific filters. In current state, the specific filters will only be available in the API. Provider registration --------------------- @@ -172,7 +265,7 @@ Search requests are processed in the ``search`` method. The ``$user`` object is The result is encapsulated in the ``SearchResult`` class that offers two static factory methods ``complete`` and ``paginated``. Both of these methods take an array of ``SearchResultEntry`` objects. -Next, you'll see a dummy provider that returns a static set of results. +Next, you’ll see a dummy provider that returns a static set of results. .. code-block:: php @@ -254,7 +347,7 @@ Each of the result entry has * A subline, e.g. the path to a file * A resource URL that makes it possible to navigate to the details of this result * Optional icon CSS class that is applied then the thumbnail URL was not set -* A boolean rounded, whether the thumbnail should be rounded, e.g. when it's an avatar +* A boolean rounded, whether the thumbnail should be rounded, e.g. when it’s an avatar Apps **may** return the full result in ``search``, but in most cases the size of the result set can become too big to fit into one HTTP request and is complicated to display to the user, hence the set should be split into chunks – it should be **paginated**. @@ -404,7 +497,7 @@ For a **cursor-based pagination** a app-specific property is used to know a refe Optional attributes ^^^^^^^^^^^^^^^^^^^ -The unified search is available via OCS, which means client application like the mobile apps can use it to get access to the server search mechanism. The default properties of a search result entry might be difficult to parse and interpret in those clients, hence it's possible to add optional string attributes to each entry. +The unified search is available via OCS, which means client application like the mobile apps can use it to get access to the server search mechanism. The default properties of a search result entry might be difficult to parse and interpret in those clients, hence it’s possible to add optional string attributes to each entry. .. code-block:: php @@ -417,6 +510,13 @@ The unified search is available via OCS, which means client application like the .. note:: This method was added in Nextcloud 21. If your app also targets Nextcloud 20 you should either not use it or add a version check to invoke the method only conditionally. +Declare in-app search +--------------------- + +If your application also have in-app search (like ``mail`` or ``talk``), your provider can also implements interface ``\OCP\Search\IInAppSearch``. + +This will add a link for it after search results. + Privacy -------