diff --git a/docs/docs/developer-guide/plugins/plugin-types/contact-search.md b/docs/docs/developer-guide/plugins/plugin-types/contact-search.md new file mode 100644 index 00000000..035a1014 --- /dev/null +++ b/docs/docs/developer-guide/plugins/plugin-types/contact-search.md @@ -0,0 +1,99 @@ +# Contact search + +Contact search provider plugins need to extend +the `ContactProvider` +class: + +```kt +class MyContactSearchPlugin() : ContactProvider( + QueryPluginConfig() +) + +``` + +In the super constructor call, pass +a `QueryPluginConfig` +object. + +## Plugin config + + + +## Search contacts + +To implement contact search, override + +```kt +suspend fun search(query: String, params: SearchParams): List +``` + +- `query` is the search term + + + +`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 + + + +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 + + + +## Plugin state + + + 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 26ad6ead..df570f70 100644 --- a/docs/docs/developer-guide/plugins/plugin-types/file-search.md +++ b/docs/docs/developer-guide/plugins/plugin-types/file-search.md @@ -5,7 +5,7 @@ the ``` - `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 @@ -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)` 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)` 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) \ No newline at end of file diff --git a/docs/docs/developer-guide/plugins/plugin-types/weather.md b/docs/docs/developer-guide/plugins/plugin-types/weather.md index a0bf6929..68d3ea34 100644 --- a/docs/docs/developer-guide/plugins/plugin-types/weather.md +++ b/docs/docs/developer-guide/plugins/plugin-types/weather.md @@ -5,7 +5,7 @@ the `getLocationName` - 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 `getLocationName` + 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) diff --git a/docs/docs/developer-guide/sidebar.ts b/docs/docs/developer-guide/sidebar.ts index a58121de..010ba714 100644 --- a/docs/docs/developer-guide/sidebar.ts +++ b/docs/docs/developer-guide/sidebar.ts @@ -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',