From 4fe44dbd89f6162f747c876e3a3dc962e959e3ce Mon Sep 17 00:00:00 2001
From: MM20 <15646950+MM2-0@users.noreply.github.com>
Date: Sat, 10 Feb 2024 01:47:38 +0100
Subject: [PATCH] Add file search plugin docs
---
.../common/_search_plugin_config.md | 5 ++
.../plugins/plugin-types/file-search.md | 53 ++++++++++++++++++-
.../plugins/plugin-types/weather.md | 6 +++
3 files changed, 63 insertions(+), 1 deletion(-)
create mode 100644 docs/docs/developer-guide/plugins/plugin-types/common/_search_plugin_config.md
diff --git a/docs/docs/developer-guide/plugins/plugin-types/common/_search_plugin_config.md b/docs/docs/developer-guide/plugins/plugin-types/common/_search_plugin_config.md
new file mode 100644
index 00000000..ce3827e0
--- /dev/null
+++ b/docs/docs/developer-guide/plugins/plugin-types/common/_search_plugin_config.md
@@ -0,0 +1,5 @@
+Search plugins have the following configuration properties:
+
+- `storageStrategy`: Describes how the launcher should store a search result in its internal database. This is relevant when a user pins a search result to favorites, or when they assign a tag or custom label. In these situations, the launcher needs to be able to restore the search result from its database. There are two different strategies:
+ - **`StorageStrategy.StoreReference`**: The launcher only stores the ID of the search result, and the plugin that created it. To restore a result, the plugin is queried again. This strategy allows the plugin provider to update a search result at a later point in time. However, plugins that use this strategy must guarantee that a search result can be restored in a timely manner. In particular, the plugin provider must be able to restore a search result without any network requests.
+ - **`StorageStrategy.StoreCopy`** (default): The launcher stores all relevant information about this search result in its own internal database. The result can be restored without querying the plugin again. This strategy is very easy to implement. The downside is, that results cannot be updated at a later point in time.
diff --git a/docs/docs/developer-guide/plugins/plugin-types/file-search.md b/docs/docs/developer-guide/plugins/plugin-types/file-search.md
index 73038940..dcc8bf65 100644
--- a/docs/docs/developer-guide/plugins/plugin-types/file-search.md
+++ b/docs/docs/developer-guide/plugins/plugin-types/file-search.md
@@ -1,6 +1,57 @@
# File Search
-TODO
+File search provider plugins need to extend the `FileProvider` class:
+
+```kt
+class MyFileSearchPlugin : FileProvider(
+ SearchPluginConfig()
+)
+
+```
+
+In the super constructor call, pass a `SearchPluginConfig` object.
+
+## Plugin config
+
+
+
+## Search files
+
+To implement file search, override
+
+```kt
+suspend fun search(query: String, allowNetwork: Boolean): List
+```
+
+- `query` is the search term
+- `allowNetwork` is a flag that indicates whether the user has enabled online search for this query. Plugins are generally advised to respect this request. This flag exists mainly for privacy reasons: the majority of searches target offline results (like apps, or contacts). Sending every single search request to external servers is overkill and can be a privacy issue. (Besides, it's not very nice to overload servers with unnecessary requests.) To reduce the amount of data that is leaked to external servers, users can control, whether a search should include online results or not.
+
+`search` returns a list of `File`s. The list can be empty if no results were found.
+
+### The `File` object
+
+A `File` has the following properties:
+
+- `id`: A unique and stable identifier for this file. This is used to track usage stats so if two files are identical, they must have the same ID, and if they are different, they need to have different IDs.
+- `uri`: A URI that is used to open the file.
+- `displayName`: The name that is shown to the user
+- `mimeType`: The MIME type of the file. This is only used for informational purposes, i.e. to determine the icon.
+- `size`: The file size in bytes.
+- `path`: The file path. This is shown for informational purposes. It is not used to read or open the file.
+- `isDirectory`: Whether the file is a folder. If true, a folder icon is shown.
+- `thumbnailUri`: An optional URI to a file thumbnail. Supported schemes are: `content`, `file`, `android.resource`, `http`, and `https`. If this is a `content` URI, make sure that the launcher has the permissions to access it.
+- `owner`: The name of the owner of the file. This is mainly relevant for files that are stored in a cloud drive and are not owned by the user themselves, but shared with them.
+- `metadata`: Additional file metadata.
+
+## Get a file
+
+If you have set `config.storageStrategy` to `StorageStrategy.StoreReference`, you must override
+
+```kt
+suspend fun get(id: String): File?
+```
+
+This method is used to lookup a file by its `id`. If the file is no longer available, it should return `null`. In this case, the launcher will remove it from its database.
## Plugin state
diff --git a/docs/docs/developer-guide/plugins/plugin-types/weather.md b/docs/docs/developer-guide/plugins/plugin-types/weather.md
index 2da11141..5df459f5 100644
--- a/docs/docs/developer-guide/plugins/plugin-types/weather.md
+++ b/docs/docs/developer-guide/plugins/plugin-types/weather.md
@@ -11,6 +11,12 @@ class MyWeatherProviderPlugin : WeatherProvider(
In the super constructor call, pass a `WeatherPluginConfig` object.
+## Plugin config
+
+In the plugin config, you can set the following properties:
+
+- `minUpdateInterval`: Minimum time (in ms) that needs to pass before the provider can be queried again. The launcher respects this value as long as the user does not change the weather settings (provider or location).
+
## Location search
If your weather provider service provides an API to lookup locations, you should override