From 3cb8e61f3436914576ac44286a64fdbae5e48eb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Menu?= Date: Mon, 4 Mar 2024 12:14:38 +0100 Subject: [PATCH] 3.0.0-alpha.2 (#480) --- .idea/kotlinScripting.xml | 6 -- CHANGELOG.md | 13 +++- README.md | 2 +- docs/migration-guide.md | 138 ++++++++++---------------------------- gradle.properties | 2 +- test-app/build.gradle.kts | 2 +- 6 files changed, 50 insertions(+), 113 deletions(-) delete mode 100644 .idea/kotlinScripting.xml diff --git a/.idea/kotlinScripting.xml b/.idea/kotlinScripting.xml deleted file mode 100644 index bc444dead9..0000000000 --- a/.idea/kotlinScripting.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 156124b6f8..763396b663 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,19 +4,27 @@ All notable changes to this project will be documented in this file. Take a look **Warning:** Features marked as *experimental* may change or be removed in a future release without notice. Use with caution. -## [Unreleased] + + +## [3.0.0-alpha.2] ### Added #### Navigator -* The new `HyperlinkNavigator.shouldfollowinternallink(Link, LinkContext?)` allows you to handle footnotes according to your preference. +* The new `HyperlinkNavigator.Listener.shouldFollowInternalLink(Link, LinkContext?)` allows you to handle footnotes according to your preference. * By default, the navigator now moves to the footnote content instead of displaying a pop-up as it did in version 2.x. #### LCP * You can use `LcpService.injectLicenseDocument()` to insert an LCPL into a package, if you downloaded it manually instead of using `LcpService.acquirePublication()`. +### Deprecated + +#### Shared + +* The `DownloadManager` introduced in version 3.0.0-alpha.1 has been removed due to the Android Download Manager introducing unnecessary complexities in the toolkit. Instead, we chose to enable apps to manually handle an LCP download with `LcpService.injectLicenseDocument()`. + ## [3.0.0-alpha.1] @@ -798,4 +806,5 @@ progression. Now if no reading progression is set, the `effectiveReadingProgress [2.3.0]: https://github.com/readium/kotlin-toolkit/compare/2.2.1...2.3.0 [2.4.0]: https://github.com/readium/kotlin-toolkit/compare/2.3.0...2.4.0 [3.0.0-alpha.1]: https://github.com/readium/kotlin-toolkit/compare/2.4.0...3.0.0-alpha.1 +[3.0.0-alpha.2]: https://github.com/readium/kotlin-toolkit/compare/3.0.0-alpha.1...3.0.0-alpha.2 diff --git a/README.md b/README.md index e091d183dc..9430377292 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Readium modules are distributed with [Maven Central](https://search.maven.org/se ```groovy buildscript { - ext.readium_version = '3.0.0-alpha.1' + ext.readium_version = '3.0.0-alpha.2' } allprojects { diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 1b2c09bcf2..09ae339e6e 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -2,6 +2,40 @@ All migration steps necessary in reading apps to upgrade to major versions of the Kotlin Readium toolkit will be documented in this file. +## 3.0.0-alpha.2 + +### Deprecation of `DownloadManager` + +The `DownloadManager` introduced in version 3.0.0-alpha.1 has been removed due to the Android Download Manager introducing unnecessary complexities in the toolkit. Instead, we chose to enable apps to manually handle an LCP download with `LcpService.injectLicenseDocument()`. + +### EPUB footnote pop-ups + +The EPUB navigator no longer displays a pop-up when the user activates a footnote link. This change was made to give reading apps control over the entire user interface. + +The navigator now moves to the footnote content by default. To show your own pop-up instead, implement the new callback `HyperlinkNavigator.Listener.shouldFollowInternalLink(Link, LinkContext?)`. + +```kotlin +override fun shouldFollowInternalLink( + link: Link, + context: HyperlinkNavigator.LinkContext? +): Boolean = + when (context) { + is HyperlinkNavigator.FootnoteContext -> { + val text = + if (link.mediaType?.isHtml == true) { + Html.fromHtml(context.noteContent, Html.FROM_HTML_MODE_COMPACT) + } else { + context.noteContent + } + + showPopup(text) + false + } + else -> true + } +``` + + ## 3.0.0-alpha.1 First of all, upgrade to version 2.4.0 and resolve any deprecation notices. This will help you avoid troubles, as the APIs that were deprecated in version 2.x have been removed in version 3.0. @@ -174,115 +208,15 @@ navigator.addInputListener(object : InputListener { #### Creating an `LcpService` -The `LcpService` now requires an instance of `AssetRetriever` and `DownloadManager` during construction. To get the same behavior as before, you can use a `ForegroundDownloadManager`. If you want to support downloads in the background instead, take a look at `AndroidDownloadManager`. +The `LcpService` now requires an instance of `AssetRetriever` during construction. ```kotlin val lcpService = LcpService( context, - assetRetriever = assetRetriever, - downloadManager = ForegroundDownloadManager( - httpClient = httpClient, - downloadsDirectory = File(context.cacheDir, "lcp") - ) + assetRetriever = assetRetriever ) ``` -#### Downloading an LCP protected publication from a license - -`LcpService.acquirePublication()` is deprecated in favor of `LcpService.publicationRetriever()`, which provides greater flexibility thanks to the `DownloadManager`. - -```kotlin -// 1. Open an `Asset` from a `File`. -val asset = assetRetriever.retrieve(file) - .getOrElse { /* Failed to open the file or sniff its format */ } - -// 2. Verify that it is an LCP License Document. -if (asset is ResourceAsset && asset.format.conformsTo(LcpLicenseSpecification)) { - // 3. Parse the LCP License Document from its JSON representation. - val license = lcplAsset.resource.read() - .getOrElse { /* Failed to read the content of the LCPL asset */ } - .let { LicenseDocument.fromBytes(it) } - .getOrElse { /* Failed to parse a valid LCP License Document from the the raw bytes */ } - - // 4. Download the publication using the `LcpPublicationRetriever`. - // The returned `requestId` can be used to cancel an on-going download, or to resume a download - // with `LcpPublicationRetriever.register()`, if it was downloaded in the background. - val requestId = lcpService.publicationRetriever() - .retrieve(license, listener = object : LcpPublicationRetriever.Listener { - override fun onAcquisitionCompleted( - requestId: LcpPublicationRetriever.RequestId, - acquiredPublication: LcpService.AcquiredPublication - ) { - } - - override fun onAcquisitionProgressed( - requestId: LcpPublicationRetriever.RequestId, - downloaded: Long, - expected: Long? - ) { - // Report progress. - } - - override fun onAcquisitionFailed( - requestId: LcpPublicationRetriever.RequestId, - error: LcpError - ) { - // Report error. - } - - override fun onAcquisitionCancelled(requestId: LcpPublicationRetriever.RequestId) { - // Handle cancellation. - } - }) -} -``` - -If you are using a `ForegroundDownloadManager` and **not supporting background downloads**, you can use this helper to have a similar API as Readium 2.x with coroutines. - -```kotlin -suspend fun LcpService.acquirePublication( - lcplAsset: ResourceAsset, - onProgress: (Double) -> Unit -): Try { - require(lcplAsset.format.conformsTo(LcpLicenseSpecification)) - - val license = lcplAsset.resource.read() - .flatMap { LicenseDocument.fromBytes(it) } - .getOrElse { return Try.failure(it) } - - return suspendCancellableCoroutine { cont -> - publicationRetriever().retrieve(license, object : LcpPublicationRetriever.Listener { - override fun onAcquisitionCompleted( - requestId: LcpPublicationRetriever.RequestId, - acquiredPublication: LcpService.AcquiredPublication - ) { - cont.resume(Try.success(acquiredPublication)) - } - - override fun onAcquisitionProgressed( - requestId: LcpPublicationRetriever.RequestId, - downloaded: Long, - expected: Long? - ) { - expected ?: return - onProgress(downloaded.toDouble() / expected.toDouble()) - } - - override fun onAcquisitionFailed( - requestId: LcpPublicationRetriever.RequestId, - error: LcpError - ) { - cont.resume(Try.failure(error)) - } - - override fun onAcquisitionCancelled(requestId: LcpPublicationRetriever.RequestId) { - cont.cancel() - } - }) - } -} -``` - #### `LcpDialogAuthentication` updated to support configuration changes The way the host view of a `LcpDialogAuthentication` is retrieved was changed to support Android configuration changes. You no longer need to pass an activity, fragment or view as `sender` parameter. diff --git a/gradle.properties b/gradle.properties index f0436688ce..7befbeb1ea 100644 --- a/gradle.properties +++ b/gradle.properties @@ -6,7 +6,7 @@ # http://www.gradle.org/docs/current/userguide/build_environment.html pom.groupId=org.readium.kotlin-toolkit -pom.version=3.0.0-alpha.1 +pom.version=3.0.0-alpha.2 android.minSdk=21 android.compileSdk=34 diff --git a/test-app/build.gradle.kts b/test-app/build.gradle.kts index fb9302e81e..e534e2eff2 100644 --- a/test-app/build.gradle.kts +++ b/test-app/build.gradle.kts @@ -19,7 +19,7 @@ android { applicationId = "org.readium.r2reader" - versionName = "3.0.0-alpha.1" + versionName = "3.0.0-alpha.2" versionCode = 300000 testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"