The Palace Project Android Readium 2 navigator component.
Image by Jose Antonio Alba from Pixabay
The contents of this repository define an API and a set of views for working with the Readium 2 library.
Make sure you clone this repository with git clone --recursive.
If you forgot to use --recursive, then execute:
$ git submodule init
$ git submodule update --remote --recursive
The architecture of the project is modularized and carefully structured to separate presentation and logic, and to clearly distinguish between functionality provided by the project and functionality that must be provided by the hosting application.
The org.librarysimplified.r2.api module defines a controller API that accepts
commands and publishes events in response to those commands. A controller encapsulates
a Readium Publication. A single controller instance has
a lifetime matching that of the Publication; when the user wants to open a book,
a new controller instance is created for that book, and then destroyed when the
user closes the book.
The controller accepts commands in the form of values of a sealed SR2Command type. Commands
are accepted by the controller and executed serially and asynchronously. The controller is
thread-safe and commands can be submitted from any thread - a single-threaded executor is used
internally to execute commands in submission order and without interleaving command executions.
The controller exposes an rxjava Observable stream
of events to which subscribers can react. The events are values of a sealed SR2Event type,
so consumers of the events are given static guarantees that they have handled all possible events
(assuming that they use total when expressions to examine the events).
Readium requires a WebView
in order to execute JavaScript code, the controller API provides methods to dynamically
attach and detach a WebView in accordance with the Android Fragment lifecycle; the
controller is responsible for effectively managing state such as the currently
selected color scheme, the current reading position, and is responsible for correctly
restoring this state each time a WebView is (re)connected.
The org.librarysimplified.r2.views module defines a set of Android Fragments that implement a simple user interface for displaying a book and allowing the user to manage bookmarks and choose items from the book's table of contents. The fragments are stateless views that simply respond to events published by the current controller instance.
The user's application has the following responsibilities:
-
The application must instantiate the
SR2ReaderFragmentand attach it to an activity. -
The application should subscribe to the controller instance's event stream in order to perform actions such as saving and retrieving bookmarks from its own internal database. Failing to handle events will merely result in bookmarks not being saved.
-
The application must respond to requests from the fragments to instantiate other fragments. For example, when the user clicks the table of contents button in the
SR2ReaderFragment, an event will be published indicating that the user's application should now instantiate and attach aSR2TOCFragmentin order to show the table of contents. Failing to handle these events will merely result in a UI that does nothing when the user selects various menu items.
An extremely minimal demo application is included that describes the bare minimum an application can do in order to provide a basic reading experience.
| Module | Description |
|---|---|
| org.librarysimplified.r2.api | R2 API |
| org.librarysimplified.r2.demo | R2 demo application |
| org.librarysimplified.r2.ui_thread | R2 UI Thread service |
| org.librarysimplified.r2.vanilla | R2 vanilla implementation |
| org.librarysimplified.r2.views | R2 views |