Introduction to the epub-js library

The epub-js is an open-source JavaScript library for rendering EPUB documents in the browser on many devices. Essentially, this library provides an interface for common ebook features (such as rendering, persistence and pagination) without the need to develop a dedicated application or plugin.

In addition, some components of the epub-js library can also be used in commonjs projects on the server.

Why was this fork created

Initially, the main reason for creating the intity/epub-js fork (hereinafter epub-js) was to fix the problems of the deprecated API.

However, upon closer examination of the source code of the futurepress/epub.js library, architectural problems related to dynamic layout rebuilding were discovered. As a result, the architecture of the epub-js library was significantly reworked, which led to a violation of the backward compatibility of the API.

Why EPUB

The EPUB standard is a widely used and easily convertible format. Many books are currently in this format, and it is convertible to many other formats (such as PDF, Mobi and iBooks).

An unzipped EPUB3 is a collection of HTML5 files, CSS, images and other media – just like any other website. However, it enforces a schema of book components, which allows us to render a book and its parts based on a controlled vocabulary.

More specifically, the EPUB schema standardizes the table of contents, provides a manifest that enables the caching of the entire book, and separates the storage of the content from how it’s displayed.

Development goals

The new stage of development of the epub-js library assumes a higher quality level of optimization and API testing. To achieve this goal, a deep understanding of the specifics of the application of technologies that form the basis of this library is required. The main task of development is to reach the optimization limit through unit testing.

In addition, it is necessary to develop a scheme that will allow configuring library components at the build stage, excluding unused code.

A secondary goal is to develop documentation that should make it easier for the community to learn the API, which includes a detailed description of the architecture and various methods for configuring the epub-js library.

Getting Started

If using archived .epub files include JSZip (this must precede inclusion of epub.js):

<script src="../dist/jszip.min.js"></script>

Get the minified code from the build folder:

<script src="../dist/epub.min.js"></script>

Set up a element to render to:

<div id="viewport"></div>

Create the new ePub, and then render it to that element:

<script>
  const book = ePub("uri/to/book.epub")
  const rend = book.renderTo("viewport", {
    width: 600,
    height: 400
  })
  rend.display().then((section) => {
    console.log(section)
  })
</script>

Setting up the render manager

A rendering manager is an entity that defines the base class of content generation. Preloaded documents from the EPUB container are added to the DOM structure to be rendered during the rendering stage. The epub-js library provides two rendering managers: default and continuous.

Default configuration:

book.renderTo("viewport", {
  manager: "default"
})

The default manager renders one section at a time, using minimal device resources. The default configuration is more suitable for devices where navigation is controlled only by a keyboard or mouse.

Example: examples/paginated.html

Configuration with continuous rendering manager:

book.renderTo("viewport", {
  manager: "continuous"
})

The continuous manager creates a continuous flow of scrollable area composed of a set of sections.

Examples (for mobile devices):

• examples/paginated-continuous.html
• examples/scrolled-continuous.html

Setting up the flow

Flow is a layout property that determines how pages are reflowed. The epub-js library provides the following types for the flow property:

• paginated
• scrolled
• scrolled-doc

Default configuration:

book.renderTo("viewport", {
  flow: "paginated"
})

The paginated type defines a method for rearranging the document content into columns. Each column represents a page that moves along the horizontal axis within the visible portion of the viewport container. Pages that extend beyond the visible portion of the container are always hidden. In fact, the entire viewport container moves. However, the horizontal scrolling mechanism is hidden from the user so that only a quick change of frames is displayed on the visible portion of the container.

Example: examples/paginated.html

Configuration of a scrolled flow:

book.renderTo("viewport", {
  flow: "scrolled"
})

The scrolled type defines a method for reflowing the document's content across the width of the viewport container, with the scrollable area hidden along the vertical axis.

Example: examples/scrolled.html

Configuration of a scrolled-doc flow:

book.renderTo("viewport", {
  flow: "scrolled-doc",
  pageWidth: 800
})

The scrolled-doc type is an extension of the scrolled type. This type makes it easy to customize the layout of pages within the boundaries defined by the pageWidth property.

Example: examples/scrolled-doc.html

Embedded Scripts

Scripted content (or embedded JavaScript) is disabled by default due to the potential for malicious code execution. However, if needed, you can configure sandbox permissions in the rendering configuration, for example:

book.renderTo("viewport", {
  sandbox: [
    "allow-same-origin",
    "allow-scripts"
  ]
})

This will thus allow sandboxed content to run scripts.

Technically, this is done by sandboxing the iframe element in which the content is rendered. It is also recommended to clean the server-side of the EPUB content.

Hooks

Similar to a plugins, epub.js implements events that can be "hooked" into. Thus you can interact with and manipulate the contents of the book.

Examples of this functionality is loading videos from YouTube links before displaying a chapter's contents or implementing annotation.

Hooks require an event to register to and a can return a promise to block until they are finished.

Example hook:

rendition.hooks.content.register((contents, view) => {
  const items = contents.document.querySelectorAll("[video]")
  items.forEach((item) => {
    // do something with the video item
  })
})

For more details, see the related section of the Hooks documentation.

Documentation

All documentation is available at docs/index.md.

Running a local server

install node.js

Then install the project dependences with npm

npm install

You can run the reader locally with the command

npm run start

Examples

You can find all the source code for the examples in the epub-js/examples subsection of the repository.

Please note: not all examples work; some may be outdated.

You can find a list of working examples on the Examples page.

There is also a project epubreader-js, which implements the main features of the library futurepress/epub.js.

Testing

The mocha framework is used for unit testing. All tests are performed in the browser console. First, you need to start the local server with the following command:

npm run start

Then open the page in the browser at: /test/

Finally, open the browser console to see the test results.

Building and distribution

Builds are concatenated and minified using webpack and babel

To generate a new build run

npm run prepare

or to continuously build run

npm run watch

License

URL: https://opensource.org/license/bsd-2-clause