Readium Web
Guidelines for an implementation of the Readium Architecture for Web-based platforms.
Editors:
- Juan Corona (Evident Point)
Participate:
Document status: DRAFT
1. Introduction
1.1 Goals
- Build on the Open Web Platform
- Follow modern web development practices
- Make pragmatic use of latest web standards
- Be usable with or without a Readium Publication Server
- Support offline use cases
- Consider limited connectivity, low-spec clients
- Be compatible with Assistive Technologies
- Be mindful of performance jank, focus on speed
- Offer a acceptable level of content protection.
1.2 Non-Goals
- User Interface implementations
- Browser incompatible specific APIs (Node.js)
2. Implementations
2.1 Models
- Publication
- Locators
- Injectables
2.2 Main Modules
2.2.1 Publication Parser
Turns the manifest into a working in-memory model. Understands publication structure, resources, metadata.
API:
- Parse
- Get Metadata
- Get Reading Order
- Get Resources
- Get Cover Page
- Get ToC
- Get Page List
2.2.2 Navigators
Require Publication’s Reading Order and Resource collections. Starts from a resource Link.
- HTML Navigator
- Audio Navigator
- Image Navigator
API:
- Set Reading Order & Resources
- Get Current Location
- Go Forward
- Go Backward
- Go To Location
- Set View Settings
- Location Changed Event
- Error Event
- Open External URL Event
2.2.3 Decorator
Text Highlights
Given a location (as a range) it will render highlights over the target text nodes.
Anchored Elements
Given a location (as a point) it will anchor an element over that location.
An element could be an image or other types of HTML block elements.
2.2.4 Recognizer
Recognize interactions, gestures on tap surfaces, when a text selection is made, when focus changes, and more. Emits Pointer events, which includes Mouse/Pen/Touch events.
Element Interaction
- Pointer Events
- Focus Events
Tap Regions
- Pointer Events
Gestures
- Pointer Events
- Start/Move/End (specifically)
Text Selection
- Selection API
- Select Start Event
- Selection Change Event
- Select End Event (debounced, custom event for convenience)
3. Processing Publications
Unpacked publications can be served from an HTTP web server, with resources as static assets.
Packaged publications can be streamed from a Publication Server.
To process a manifest you can start with JavaScript’s native JSON parsing to deserialize into a simple object.
With the module that implements a Publication Model you can read and manipulate a model that’s validated against the Readium Web Publication schema, with optional typing (via TypeScript) and with the addition of convenience methods.
4. Fetching Resources
Resources are fetched from a server given a web origin. Typically via HTTPS, initiated by the HTML processing model, and programmatically using the Fetch API.
4.1 Download Constraints
Publication resources are streamed or downloaded over networking protocols.
Contrary to other implementations that run on devices with file-system access, publication resources on the web are not, as a whole, directly or immediately accessible.
5. Loading Content
Publication resources generally need to be loaded (embedded) into the render tree (DOM) of a web-based reading system.
5.1 Embedding multimedia elements
List of content types with suggested embed elements, or other:
- HTML documents:
<iframe>, or other means of document transclusion - Audio and video:
<audio>,<video> - Images and graphics:
<img>,<picture>,<svg>,<canvas>,background-imageCSS property
6. Presenting Content
Sequencing and layout of content in reading order progression.
Match Presentation Hints.
Fragment, paginate and apply synthetic spreads.
6.1 Prefetching and Virtualization
Virtualized pagination and scrolling.
Recommended approach for implementing continuous overflow.
6.2 Performance Constraints
When loading or rendering additional resources for the purposes of prefetching and virtualization, consider frame times, DOM node count, CPU and memory heap.
Given the linear progression of a user’s reading activity it is advisable to limit the prefetching to the adjacent (previous and next) resources of a resource set in the reading progression. To effectively benefit from this approach, the adjacent resources can be fetched with high priority, as soon as or after the primary resource to render is ready.
The prefetch range could increase, with lower priority prefetching, given the known or inferred capabilities of the connected client.
7. Protecting content
Detailed guidelines are provided to developers of Web Readers who need to achieve some level of protection for copyright protected Web Publications consumed by Web applications.