Add VisualNavigator's shouldJumpToLink listener callback (#375)

Author: chrfalch

CHANGELOG.md

@@ -16,6 +16,9 @@ All notable changes to this project will be documented in this file. Take a look
     * `WebSettings.textZoom` will work with more publications than `--USER__fontSize`, even the ones poorly authored. However the page width is not adjusted when changing the font size to keep the optimal line length.
 * Scroll mode: jumping between two EPUB resources with a horizontal swipe triggers the `Navigator.Listener.onJumpToLocator()` callback.
     * This can be used to allow the user to go back to their previous location if they swiped across chapters by mistake.
+* Support for non-linear EPUB resources with an opt-in in reading apps (contributed by @chrfalch in [#375](https://github.com/readium/kotlin-toolkit/pull/375) and [#376](https://github.com/readium/kotlin-toolkit/pull/376)).
+     1. Override loading non-linear resources with `VisualNavigator.Listener.shouldJumpToLink()`.
+     2. Present a new `EpubNavigatorFragment` by providing a custom `readingOrder` with only this resource to the constructor.
 
 #### Streamer
 

readium/navigator/src/main/java/org/readium/r2/navigator/Navigator.kt

@@ -136,6 +136,18 @@ interface VisualNavigator : Navigator {
     }
 
     interface Listener : Navigator.Listener {
+
+        /**
+         * Called when a link to an internal resource was clicked in the navigator.
+         *
+         * You can use this callback to perform custom navigation like opening a new window
+         * or other operations.
+         *
+         * By returning false the navigator wont try to open the link itself and it is up
+         * to the calling app to decide how to display the link.
+         */
+        fun shouldJumpToLink(link: Link): Boolean { return true }
+
         /**
          * Called when the user tapped the content, but nothing handled the event internally (eg.
          * by following an internal link).

readium/navigator/src/main/java/org/readium/r2/navigator/epub/EpubNavigatorFragment.kt

@@ -270,6 +270,7 @@ class EpubNavigatorFragment internal constructor(
             requireActivity().application, publication,
             baseUrl = baseUrl, config = this.config,
             initialPreferences = initialPreferences,
+            listener = listener,
             layout = epubLayout,
             defaults = defaults
         )
@@ -494,7 +495,7 @@ class EpubNavigatorFragment internal constructor(
             is EpubNavigatorViewModel.Event.RunScript -> {
                 run(event.command)
             }
-            is EpubNavigatorViewModel.Event.GoTo -> {
+            is EpubNavigatorViewModel.Event.OpenInternalLink -> {
                 go(event.target)
             }
             EpubNavigatorViewModel.Event.InvalidateViewPager -> {
@@ -1040,7 +1041,8 @@ class EpubNavigatorFragment internal constructor(
          * if you use a local HTTP server.
          * @param initialLocator The first location which should be visible when rendering the
          * publication. Can be used to restore the last reading location.
-         * @param readingOrder custom reading order
+         * @param readingOrder Custom order of resources to display. Used for example to display a
+         * non-linear resource on its own.
          * @param listener Optional listener to implement to observe events, such as user taps.
          * @param config Additional configuration.
          */

readium/navigator/src/main/java/org/readium/r2/navigator/epub/EpubNavigatorViewModel.kt

@@ -52,6 +52,7 @@ internal class EpubNavigatorViewModel(
     val config: EpubNavigatorFragment.Configuration,
     initialPreferences: EpubPreferences,
     val layout: EpubLayout,
+    val listener: VisualNavigator.Listener?,
     private val defaults: EpubDefaults,
     baseUrl: String?,
     private val server: WebViewServer?,
@@ -76,7 +77,7 @@ internal class EpubNavigatorViewModel(
     }
 
     sealed class Event {
-        data class GoTo(val target: Link) : Event()
+        data class OpenInternalLink(val target: Link) : Event()
         data class OpenExternalLink(val url: Uri) : Event()
         /** Refreshes all the resources in the view pager. */
         object InvalidateViewPager : Event()
@@ -205,7 +206,9 @@ internal class EpubNavigatorViewModel(
         val href = url.toString()
         val link = internalLinkFromUrl(href)
         if (link != null) {
-            _events.send(Event.GoTo(link))
+            if (listener?.shouldJumpToLink(link) == true) {
+                _events.send(Event.OpenInternalLink(link))
+            }
         } else {
             _events.send(Event.OpenExternalLink(url))
         }
@@ -384,12 +387,13 @@ internal class EpubNavigatorViewModel(
             publication: Publication,
             baseUrl: String?,
             layout: EpubLayout,
+            listener: VisualNavigator.Listener?,
             defaults: EpubDefaults,
             config: EpubNavigatorFragment.Configuration,
             initialPreferences: EpubPreferences
         ) = createViewModelFactory {
             EpubNavigatorViewModel(
-                application, publication, config, initialPreferences, layout,
+                application, publication, config, initialPreferences, layout, listener,
                 defaults = defaults,
                 baseUrl = baseUrl,
                 server = if (baseUrl != null) null