Skip to content

ThePalaceProject/android-r2

Repository files navigation

android-r2

Build Status Maven Central Maven Central (snapshot)

The Palace Project Android Readium 2 navigator component.

r2

Image by Jose Antonio Alba from Pixabay

What Is This?

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

Architecture

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.

Architecture

Controller

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.

Commands

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.

Events

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).

Web Views

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.

Views

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.

Usage

The user's application has the following responsibilities:

  • The application must instantiate the SR2ReaderFragment and 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 a SR2TOCFragment in 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.

Modules

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