Evolution of the Navigator API

[mickael-menu]

With the version 2.0.0 of Readium Toolkit just around the corner, it's time to figure out how we will approach the next big refactoring project: a revamped Navigator API.

We have reached a point where it's difficult to make further improvements without breaking the existing navigator APIs (activities and fragments). They are currently exposing too much internals (resource pagers, web view subclasses, etc.) and have an ill-defined API binding us to the current implementation details.

Rewriting the Navigator internals will take months, but we cannot bring the rest of the toolkit to a halt until we are ready to ship a new Navigator. That's why we decided in our weekly team call of the following approach:

• The current navigator API (e.g. R2EpubActivity, EpubNavigatorFragment) will be "frozen" in the current state, with only bug fixes (when contributed) shipped in future 2.x versions.
• In parallel, we will develop Navigator2 components which will implement the new API. They will be in an alpha/beta state and marked as explicit OptIn. The API may break between two versions while we figure things out.
• Once Navigator2 reach maturity and feature parity with the legacy Navigator, we will release version 3.0.0 of the Readium Toolkit and replace the legacy API.

Focus for the new API

Here are the points we should keep in focus while developing Navigator2:

• Ease of use/integration.
• Communication between the reading app and the Navigator will be explicit, documented and follow Android's best practices.
• Everything will be private except a limited and specified API (We already have some of it) and Android basic APIs (Activity, Fragment, View).
  • This means that an external vendor could provide a Navigator implementing the same API to be able to swap implementations without changing the reading app. Such public APIs will probably need to be moved to r2-shared-kotlin for this reason.
• The API will provide "building blocks" to build higher level features. For example:
  • an injectable API will handle injecting CSS, JavaScript, fonts, etc.
  • a decoration API could be used to draw highlights, search results, TTS, etc.
• User settings models (not UX) will be media type-agnostic and implemented in the Navigator instead of in the reading app.
  • It will be opened to media type custom extensions though (e.g. raw CSS).
  • It will honor RWPM Presentation Hints.
  • The Navigator will refresh itself as necessary when user settings are modified, instead of having the reading app calling manually JavaScript methods in the web views.
• Internals will implement a clear statechart to make sure out-of-order/excess commands cannot break the navigation.

Where to start?

• @stevenzeck already made significant changes in the current Navigator to use ViewPager2. We could start from there and remove/modify existing APIs without fear of breaking apps.
• NYPL would love to contribute a rewrite of a Navigator which could serve as a fresh start.

[killerpuppytails]

Change "might" to "would love to"

[stevenzeck]

There are several large initiatives that need to be done with the navigator:

• Highlights
• ViewPager2
• Replacing the web server

Would it make more sense to start rewriting the navigator with these and everything above in mind rather than fix the current one?

[mickael-menu]

Yes that's the plan, starting from scratch and cherry-picking existing pieces when needed.

[mickael-menu]

Type of objects exposed by the navigator

To keep things flexible but easy-to-use I suggest a "russian dolls" approach.

Low-level: View / Controller

• A stateless NavigatorView handling the rendering / layout of the publication.
• A stateful Navigator controller object exposing the higher-level public API and holding the current state of the navigator.

High-level: Fragment / ViewModel

For a more integrated approach, we could wrap these two components in easy-to-use objects.

• A NavigatorFragment creating and owning the NavigatorView and the NavigatorViewModel.
• A NavigatorViewModel to:
  • hold the Navigator controller object
  • handle configuration changes

Thoughts?

[jerome65536]

Some way of distinguishing requests to change page due to user input from changing page due to some other reason would be good.

[mickael-menu]

Use case:

to be able to go into full-screen mode automatically when the user changes page or taps, but not in any other case (such as due to repaginating due to coming out of full-screen mode)

[mickael-menu]

Another use case:

how to detect a scroll drag in the reader?
i'd like to present a popup when user taps on editing action, and remove it if the user scrolls

[mickael-menu]

More requirements:

• The app should be able to display a single standalone resource pulled from a linear publication, for example to see previews, parallel reading with a single Navigator or display non-linear resources in a pop-up.
• The navigator should be able to render several times the same resource, or several resources of the same publication for parallel reading.
• The app should be able to mark a resource as "important" to prevent the navigator from clearing it from its internal in-memory cache. This allows instant switches between two resources that are potentially far apart.

[mickael-menu]

Some initial work to migrate to ViewPager2 #148 which could be relevant.

cc @stevenzeck

[mickael-menu]

Also see #150