Minimum code to get an epub reader running

[mrifni]

Whats like the minimum code needed to get an epub reader running using both streamer and navigator apis ?

[mickael-menu]

1. Parse an EPUB file into a Publication model using the Streamer

val streamer = Streamer(context)
val epubFile = File(...)
val publication = streamer.open(FileAsset(epubFile))
    .getOrElse { error ->
        val message = error.getUserMessage(context)
    }

2. Add the Publication to the local HTTP server to serve the EPUB content

(We want to remove this step eventually, it depends on https://github.com/readium/r2-testapp-kotlin/issues/297)

// See `R2App` in the test app for an example on how to manage the server.
val s = ServerSocket(0)
s.close()
val server = Server(s.localPort, context)
server.start()

// The base URL will be necessary to create the EPUB navigator
val baseUrl = server.addPublication(
    publication,
    // See `UserSettings.kt` in the test app for saving user properties (styles, font size, etc.)
    userPropertiesFile = File("path/to/UserProperties.json")
)

3. Create a factory for EpubNavigatorFragment

val factory = EpubNavigatorFragment.createFactory(
    publication = publication,
    baseUrl = baseUrl,
    initialLocator = lastSavedLocatorFromDatabase,
    listener = yourListener
)

The EpubNavigatorFragment only provides:

• Rendering and scrolling through the EPUB pages
• Reporting the current location (Locator object)
• Navigating to other locations (e.g. a Link from the table of contents)
• A listener for events such as "onTap"

What the EpubNavigatorFragment doesn't provide:

• There is no user interface except for the EPUB content, the UX is up to you in the parent Fragment / Activity.
• Highlights are not supported by EpubNavigatorFragment. They are implemented in R2EpubActivity but the integration is complicated so I would wait for the support to be added to Navigator2

4. Present the EPUB navigator fragment in an Activity

This part is up to you, the test app is using R2EpubActivity so it's not a good example of using EpubNavigatorFragment. This part is normal Android development so you should check out Android's guides on how to use a Fragment factory.

What you could/should do:

• Toggling a custom action bar / toolbars when receiving the EpubNavigatorFragment.Listener.onTap() event.
• Observing navigatorFragment.currentLocator to save the last location in your database, to be used as the initialLocation when creating the EpubNavigatorFragment.

5. What to expect for the future of the toolkit

Some steps are still a bit complicated to integrate in the current version of Readium, and we want to improve these areas in Navigator2:

• Get rid of the HTTP server.
• Simpler user settings API integrated in the Navigator.
• Add a Decorator API to implement highlights in EpubNavigatorFragment.

[mrifni]

should Streamer object be a singleton or instantiated everytime a book is to be open ?

[mickael-menu]

As you want, you can have several instances of Streamer and sometimes it makes sense if you want to customize some of its features for a publication.

You should have a single instance of Server though.