NetNewsWire/Technotes/Widgets.md

53 lines
1.9 KiB
Markdown
Raw Normal View History

2020-11-18 06:42:32 +01:00
# Widgets on iOS
There are _currently_ seven widgets available for iOS:
2020-11-18 06:42:32 +01:00
- 1x small widget that displays the current count of each of the Smart Feeds
2020-11-18 06:42:32 +01:00
- 3x medium widgets—one for each of the smart feeds.
- 3x large widgets—bigger versions of the medium widgets
2020-11-18 06:42:32 +01:00
## Widget Data
The widget does not have access to the parent app's database. To surface data to the widget, a small amount of article data is encoded to JSON (see `WidgetDataEncoder`) and saved to the AppGroup container.
Widget data is written at three points:
1. After applicationDidFinishLaunching
2. As part of a background refresh
3. When the scene enters the background
The widget timeline is refreshed—via `WidgetCenter.shared.reloadAllTimelines()`—after each of the above.
## Deep Links
The medium widgets support deep links for each of the articles that are surfaced.
2020-11-18 06:45:20 +01:00
If the user taps on an unread article in the unread widget, the widget opens the parent app with a deep link URL (see `WidgetDeepLink`), for example: `nnw://showunread?id={articeID}`. Once the app is opened, `scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>)` is called and it is then determined what should be presented to the user based on the URL. If there is no `id` parameter—the user has tapped on a small widget or a non-linked item in a medium widget—the relevant smart feed controller is displayed.
2020-11-18 06:42:32 +01:00
## Data Models
```swift
struct WidgetData: Codable {
let currentUnreadCount: Int
let currentTodayCount: Int
let currentStarredCount: Int
let unreadArticles: [LatestArticle]
let starredArticles: [LatestArticle]
let todayArticles: [LatestArticle]
let lastUpdateTime: Date
}
struct LatestArticle: Codable, Identifiable {
var id: String // articleID
let feedTitle: String
let articleTitle: String?
let articleSummary: String?
let feedIcon: Data? // Base64 encoded image
let pubDate: String
}
```