khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-02 17:59:36 +07:00
Code Issues Packages Projects Releases Wiki Activity

Documentation for advanced search

Browse Source 
Signed-off-by: Benjamin Gaussorgues <benjamin.gaussorgues@nextcloud.com>
This commit is contained in:
Benjamin Gaussorgues
2023-11-24 10:58:33 +01:00
parent 371e73756f
commit e0bcbfe770
1 changed files with 115 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
developer_manual/digging_deeper/search.rst
View File

@@ -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<dependency-injection>`.
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<dependency-injection>`.
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
<?php
declare(strict_types=1);
namespace OCA\MyApp\Search;
use OCA\MyApp\AppInfo\Application;
use OCP\IUser;
use OCP\Search\FilterDefinition;
use OCP\Search\IFilteringProvider;
class Provider implements IFilteringProvider {
// TODO Implement functions from simple search provider
public function getSupportedFilters(): array {
return [
'term',
'since',
'until',
'person',
'custom_int',
'custom_user',
'custom_bool',
];
}
public function getAlternateIds(): array {
return [];
}
public function getCustomFilters(): array {
return [
new FilterDefinition('custom_int', FilterDefinition::TYPE_INT),
new FilterDefinition('custom_user', FilterDefinition::TYPE_USER),
new FilterDefinition('custom_bool', FilterDefinition::TYPE_BOOL),
];
}
public function search(IUser $user, ISearchQuery $query): SearchResult {
// Retrieve filters
/** @var $since ?DateTimeImmutable */
$since = $query->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
-------