Exposing Fragment instead of Activity

[mickael-menu]

Currently, the navigator is exposing one Activity class for each format (e.g. R2EpubActivity), but this introduces a number of issues:

• This limits the possibilities for presenting a publication (animations, etc.) to what's available for Activity.
• It can't be used in a navigation graph to control the navigation flow.
• It's not possible to present several publications side-by-side, since activities are full-screen (not taking into account multi-window mode).
• It requires serializing parameters (such as Publication), which is a big issue if objects are too big or if we need non-data objects (e.g. DRMContext for rights handling).
• It goes against best practices that are moving towards single-Activity apps.
• The activity relies on results returned by a test-app Outline activity, which is not obvious compared to a proper public API, and forces the Outline to be presented full-screen instead of, for example, in a drawer.
  https://github.com/readium/r2-navigator-kotlin/blob/6096daf3c009bfffa76527143097f8d1aab59d65/r2-navigator/src/main/java/org/readium/r2/navigator/epub/R2EpubActivity.kt#L391-L392

Instead, we should expose a Fragment which is much more flexible and fixes all these issues.

[mickael-menu]

As stated in this video from Google, the best practice is now to have a single Activity in your app. However, there are use cases where we should have multiple activities, such as supporting multi-tasking/windows in Chrome OS. For Readium, I think it makes sense that a reader app has a main/library activity, and a reader activity, to be able to open several documents side-by-side on Chrome OS.

This should be implemented at the app level, this doesn't change the fact that the navigator should expose fragments.

However, an Activity could be provided for convenience/backward compatibility by r2-navigator. The proper way to send the Publication to this activity without sending it through the Intent (which causes crashes if the Publication is too large) could be to use an AppComponentFactory.

[stevenzeck]

Kind of curious how this will be accomplished. Yeah, ideally a library like this should not be exposing activities, that should be up to the app using the library. But decoupling six activities from here will take some time.

[mickael-menu]

@stevenzeck

@johanpoirier did most of the work already in readium/r2-navigator-kotlin#148. The strategy we applied is to move most of the activities code to the fragments and then embed the fragments in the original activities, delegating the old APIs to the fragments. You have a good example in the R2CbzActivity.

We kept some things in the activities: anything related to UX, particularly the action bar, and the code for highlights and TTS in EPUB. These features will be put back in the Fragment later, after review of the public API.

Finally, we have a NavigatorFragmentFactory to help build all these fragments without relying on arguments. Since Publication is not serializable anymore, this is quite useful.

[mickael-menu]

I merged readium/r2-navigator-kotlin#148 into the alpha branch, with the following changelog:

• (Experimental) New Fragment implementations as an alternative to the legacy Activity ones (contributed by @johanpoirier).
  • The fragments are chromeless, to let you customize the reading UX.
  • Use the new NavigatorFragmentFactory to help build the fragments, as showcased in R2PdfActivity.
  • At the moment, highlights and TTS are not yet supported in the new EPUB navigator Fragment.
  • This is now the recommended way to integrate Readium in your applications.

Even though we're not 100% there (missing highlights/TTS + audiobook), I'm closing this issue. Feel free to open a new issue to report any problem you may encounter integrating the fragments.