lun_admin/NeoLaunch_From_Kvaesitso
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Add contact search plugin docs

Browse Source
This commit is contained in:
MM20 2025-04-21 14:59:20 +02:00
parent 343986264b
commit ef003cd6c0
No known key found for this signature in database
GPG Key ID: 0B61A8F2DEAFA389
5 changed files with 139 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
docs/docs/developer-guide/plugins/plugin-types/contact-search.md Normal file
View File

@ -0,0 +1,99 @@
# Contact search
Contact search provider plugins need to extend
the <a href="/reference/plugins/sdk/de.mm20.launcher2.sdk.contacts/-contact-provider/index.html" target="_blank">`ContactProvider`</a>
class:
```kt
class MyContactSearchPlugin() : ContactProvider(
QueryPluginConfig()
)
```
In the super constructor call, pass
a <a href="/reference/core/shared/de.mm20.launcher2.plugin.config/-query-plugin-config/index.html" target="_blank">`QueryPluginConfig`</a>
object.
## Plugin config
<!--@include: ./common/_query_plugin_config.md-->
## Search contacts
To implement contact search, override
```kt
suspend fun search(query: String, params: SearchParams): List<Contact>
```
- `query` is the search term
<!--@include: ./common/_search_params.md-->
`search` returns a list of `Contact`s. The list can be empty if no results were found.
### The `Contact` object
A `Contact` has the following properties:
- `id`: A unique and stable identifier for this contact. This is used to track usage stats so if two
contacts 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 contact.
- `name`: The display name of this concact. First name + last name, if applicable.
- `photoUri`: Uri to a contact photo. If `null`, a default icon is used.
- `phoneNumbers`: A list of phone numbers for this contact. Can be an empty list.
- `emailAddresses`: A list of email addresses for this contact. Can be an empty list.
- `postalAddresses`: A list of postal addresses for this contact. Can be an empty list.
- `customActions`: Custom actions to contact this person.
#### Custom actions
Custom actions are channels handled by third party apps to contact a person. This could be a message on Slack, a voice call on WhatsApp, or a video call on Microsoft Teams. A `CustomContactAction` has the following properties:
- `label`: Label that describes the action
- `uri`: Uri that is passed the intent to start the action
- `mimeType`: Type that is passed to the intent to start the action
- `packageName`: Package name of the receiver app. If the app is not installed, the action is ignored.
## Refresh a contact
If you have set `config.storageStrategy` to `StorageStrategy.StoreCopy`, the launcher will
periodically
try to refresh the stored copy. This happens for example when a user long-presses a contact to view its
details. To update the contact, you can override
```kt
suspend fun refresh(item: Contact, params: RefreshParams): Contact?
```
The stored contact will be replaced with the return value of this method. If the contact is no longer
available, it should return `null`. In this case, the launcher will remove it from its database. If
the contact is temporarily unavailable, an exception should be thrown.
- `item` is the version that the launcher has currently stored
<!--@include: ./common/_refresh_params.md-->
The default implementation returns `item` without any changes.
## Get a contact
If you have set `config.storageStrategy` to `StorageStrategy.StoreReference`, you must override
```kt
suspend fun get(id: String, params: GetParams): Contact?
```
This method is used to lookup a contact by its `id`. If the contact is no longer available, it should
return `null`. In this case, the launcher will remove it from its database.
- `id` is the ID of the contact that is being requested
<!--@include: ./common/_get_params.md-->
## Plugin state
<!--@include: ./common/_plugin_state.md-->

2
docs/docs/developer-guide/plugins/plugin-types/file-search.md
View File

@ -5,7 +5,7 @@ the <a href="/reference/plugins/sdk/de.mm20.launcher2.sdk.files/-file-provider/i
class:
```kt
class MyFileSearchPlugin : FileProvider(
class MyFileSearchPlugin() : FileProvider(
QueryPluginConfig()
)

51
docs/docs/developer-guide/plugins/plugin-types/places-search.md
View File

@ -5,7 +5,7 @@ the <a href="/reference/plugins/sdk/de.mm20.launcher2.sdk.locations/-location-pr
class:
```kt
class MyplaceSearchPlugin : LocationProvider(
class MyplaceSearchPlugin() : LocationProvider(
QueryPluginConfig()
)
@ -28,10 +28,10 @@ suspend fun search(query: LocationQuery, params: SearchParams): List<Location>
```
- `query` includes the query parameters:
- `query`: The search term
- `userLatitude`: The latitude of the user's current location
- `userLongitude`: The longitude of the user's current location
- `radius`: The search radius in meters
- `query`: The search term
- `userLatitude`: The latitude of the user's current location
- `userLongitude`: The longitude of the user's current location
- `radius`: The search radius in meters
<!--@include: ./common/_search_params.md-->
@ -56,28 +56,28 @@ A `Location` has the following properties:
- `phoneNumber`: The phone number of the location
- `emailAddress`: The email address of the location
- `openingSchedule`: Either
- `OpeningSchedule.TwentyFourSeven` if the location is open at all times
- `OpeningSchedule.Hours(openingHours: List<OpeningHours>)` if the location has specific opening
hours, with each `OpeningHours` object containing:
- `dayOfWeek`: The day of the week, as `DayOfWeek` enum value. If a location is open past
midnight, `dayOfWeek` should refer to the day when the opening hours start.
- `startTime`: The time the location opens, as a `LocalTime` object
- `duration`: The duration the location is open, as a `Duration` object
- `OpeningSchedule.TwentyFourSeven` if the location is open at all times
- `OpeningSchedule.Hours(openingHours: List<OpeningHours>)` if the location has specific opening
hours, with each `OpeningHours` object containing:
- `dayOfWeek`: The day of the week, as `DayOfWeek` enum value. If a location is open past
midnight, `dayOfWeek` should refer to the day when the opening hours start.
- `startTime`: The time the location opens, as a `LocalTime` object
- `duration`: The duration the location is open, as a `Duration` object
- `departures`: If the place is a public transport station, this field contains the next departures
from this station. This is a list of `Departure` objects, each containing:
- `time`: The scheduled departure time as `ZonedDateTime`
- `delay`: The delay as `Duration`. If the departure is on time, this must be `Duration.ZERO`.
If no real-time data is available, this should be `null`.
- `line`: The line name (e.g. _"S1"_, _"U2"_, or _"73"_)
- `lastStop`: The destination of the line
- `type`: The type of the line, as `LineType` enum value
- `lineColor`: The color of the line, as a `Color`
- `userRating`: A user rating of this location, on a scale from 0 to 1. This is multiplied by 5
and shown as a star rating bar in the launcher.
- `userRatingCount`: The number of user ratings that were used to calculate the `userRating`
- `fixMeUrl`: A URL where users can report incorrect data for this location.
- `attribution`: Attribution that should be shown alongside the search result (read the data
provider's terms of service to find out if this is required).
- `time`: The scheduled departure time as `ZonedDateTime`
- `delay`: The delay as `Duration`. If the departure is on time, this must be `Duration.ZERO`.
If no real-time data is available, this should be `null`.
- `line`: The line name (e.g. _"S1"_, _"U2"_, or _"73"_)
- `lastStop`: The destination of the line
- `type`: The type of the line, as `LineType` enum value
- `lineColor`: The color of the line, as a `Color`
- `userRating`: A user rating of this location, on a scale from 0 to 1. This is multiplied by 5
and shown as a star rating bar in the launcher.
- `userRatingCount`: The number of user ratings that were used to calculate the `userRating`
- `fixMeUrl`: A URL where users can report incorrect data for this location.
- `attribution`: Attribution that should be shown alongside the search result (read the data
provider's terms of service to find out if this is required).
## Refresh a place
@ -122,3 +122,4 @@ return `null`. In this case, the launcher will remove it from its database.
- [Foursquare plugin](https://github.com/Kvaesitso/Plugin-Foursquare)
- [HERE plugin](https://github.com/Kvaesitso/Plugin-HERE)
- [Public transport plugin](https://github.com/shtrophic/KvaesitsoPlugin-PublicTransport)

17
docs/docs/developer-guide/plugins/plugin-types/weather.md
View File

@ -5,7 +5,7 @@ the <a href="/reference/plugins/sdk/de.mm20.launcher2.sdk.weather/-weather-provi
class:
```kt
class MyWeatherProviderPlugin : WeatherProvider(
class MyWeatherProviderPlugin() : WeatherProvider(
WeatherPluginConfig()
)
@ -100,15 +100,15 @@ a `condition`, an `icon`, a `location` name, and a `provider` name.
Similar helper functions are available to construct
- `Pressure` (`Double.hPa`, and `Double.mbar`), and
- `WindSpeed` values (`Double.m_s`, `Double.km_h`, and `Double.mph`)
- `Pressure` (`Double.hPa`, and `Double.mbar`), and
- `WindSpeed` values (`Double.m_s`, `Double.km_h`, and `Double.mph`)
- `location` is the name of the location.
- In fixed location mode, you should read this value from the `location` parameter, to ensure
that the name in the weather widget matches the name that the user has set in preferences.
- In auto location mode, if your weather service does not give you a location name, you can use
the <a href="/reference/plugins/sdk/de.mm20.launcher2.sdk.weather/-weather-provider/get-location-name.html" target="_blank">`getLocationName`</a>
method to reverse geocode the location name using Android's Geocoder API.
- In fixed location mode, you should read this value from the `location` parameter, to ensure
that the name in the weather widget matches the name that the user has set in preferences.
- In auto location mode, if your weather service does not give you a location name, you can use
the <a href="/reference/plugins/sdk/de.mm20.launcher2.sdk.weather/-weather-provider/get-location-name.html" target="_blank">`getLocationName`</a>
method to reverse geocode the location name using Android's Geocoder API.
## Plugin state
@ -118,3 +118,4 @@ a `condition`, an `icon`, a `location` name, and a `provider` name.
- [OpenWeatherMap plugin](https://github.com/Kvaesitso/Plugin-OpenWeatherMap)
- [Breezy Weather plugin](https://github.com/Kvaesitso/Plugin-BreezyWeather)
- [HERE plugin](https://github.com/Kvaesitso/Plugin-HERE)

4
docs/docs/developer-guide/sidebar.ts
View File

@ -71,6 +71,10 @@ export const DeveloperGuideSidebar: DefaultTheme.SidebarItem[] = [
text: 'File Search Provider',
link: '/docs/developer-guide/plugins/plugin-types/file-search',
},
{
text: 'Contact Search Provider',
link: '/docs/developer-guide/plugins/plugin-types/contact-search',
},
{
text: 'Places Search Provider',
link: '/docs/developer-guide/plugins/plugin-types/places-search',