Updating to v0.3 from v0.2

The 0.3 version is much better tested, better documented and brings many more options for rendering Epubs.

Unfortunately there are large breaking changes to the api, but the end result should be much simpler to work with. The Epub parsing and Rendering have been split, so many of the rendering methods & events are now available on the Rendition object instead of on ePub.

Hopefully the notes below will ease the transition, but please file bugs with your upgrade issues (labeled as v0.3-transition as they will help add to this document.

Full documentation for v0.3 is at epubjs.org/documentation.

Reader Repo

The reader has moved to its own repo at: https://github.com/futurepress/epubjs-reader/

Any issues related to reader will be moved over to there asap.

API Updates

Basic Usage

The basic usage hasn't changed much, though you can pass the path to OPF files directly or use a Webpub Manifest

var book = ePub("url/to/book/package.opf");

However you will want to assign the result of book.renderTo to a variable as this will be the way of interacting with the rendered book.

The options for ePub / new Book are documented here.

var rendition = book.renderTo("area", {width: 600, height: 400});
var displayed = rendition.display();

You must provide a width and height, though they can both be set to 100% to occupy the full size of their container;

var rendition = book.renderTo("viewer", {
  width: "100%",
  height: "100%"
});

The options for renderTo / new Rendition are documented here.

Module

You could also load npm install -s epubjs and use it as an es6 module.

import { Book, Rendition } from "epubjs";

let book = new Book("url/to/book/package.opf");
let rendition = new Rendition(book, options);

rendition.attachTo(element);

Displaying Content

Book.displayChapter and Book.goto have been combined into Rendition.display.

var rendition = book.renderTo("area", {width: 600, height: 400});
rendition.display(); // Start display at the beginning of the book
rendition.display(3); // Display the 3rd Spine item
rendition.display("chapt1.html#something"); // Display chapt1.html at position of #something
rendition.display("epubcfi(/6/30[id-id2640702]!2/4/1:0)"); // Display an EpubCFI

Book.nextPage and Book.prevPage have moved the the Rendition and renamed to not reference pages.

rendition.prev();
rendition.next();

Lifecycle Promises

Ready

book.ready returns a promise when the epub is fully parsed and ready to interact with.

book.ready.then((book) => {
	let meta = book.package.metadata; // Metadata from the package json
	let toc = book.navigation.toc; // Table of Contents
	let landmarks = book.navigation.landmarks; // landmarks
	let spine = book.spine; // landmarks
	let cover = book.cover; // landmarks
	let resources = book.resources; // landmarks
	let pageList = book.pageList; // page list (if present)
})

Getters -> Loaded Promises

Book.getToc() and other getters have been removed, but an equivalent promises are returned from book.loaded.

book.loaded.manifest.then((manifest) => { console.log(manifest) });
book.loaded.spine.then((spine) => { console.log(spine) });
book.loaded.metadata.then((metadata) => { console.log(metadata) });
book.loaded.cover.then((cover) => { console.log(cover) });
book.loaded.navigation.then((navigation) => { console.log(navigation) });
book.loaded.resources.then((resources) => { console.log(resources) });

Cover Url

book.coverUrl() will return an absolute url of the cover, even if the book is archived or a blob.

Sections

Chapters are now called Sections throughout the library, as they don't need to represent a true chapter in the book but just a HTML document in the spine.

These sections can be accessed through book.section() by index, html or cfi.

Documentation on the Section's methods is here.

Events Changes

All events are now defined in src/utils/constants.js.

Book

"book:ready" -> book.ready promise above

"book:linkClicked" -> "linkClicked" (on Rendition)

rendition.on("linkClicked", function(href) {
	console.log("Clicked", href)
});

"book:pageChanged" -> "relocated" (on Rendition)

Rendition

"renderer:chapterDisplayed" -> "rendered" which triggers after a section is rendered.

rendition.on("rendered", function(section) {
	console.log(section)
});

"renderer:resized" -> "resized"

rendition.on("resized", function(width, height) {
	console.log("Resized to:", width, height)
});

"renderer:spreads" -> "layout"

Layout event now provides if the rendering is using spreads or not, as well as other useful layout information.

rendition.on("layout", function(layout) {
	console.log(layout.spread)
});

renderer:locationChanged -> relocated

Relocated event returns an object with information about the location in the book. It contains a start and end of the current visible area of the book.

rendition.on("relocated", function(location) {
	console.log(location.start.cfi)
});

book.getCurrentLocationCfi() is now accessible though the "relocated" event or by calling rendition.currentLocation() and getting the start or end cfi.

let location = rendition.currentLocation();
let cfi = rendition.start.cfi;

More information on the location event is here;

"renderer:keydown" -> "keydown"

All the passed mouse / touch / keyboard are now accessed through the rendition.

rendition.on("keydown", function(key) {
	console.log(key)
});

Removed Events

• book:online / book:offline

Removed generatePagination

generatePagination() was far too resource intensive, as it rendered every page. It has been replaced by book.locations.generate(600) which will create a CFI for every X characters in the book.

This still needs to load every section in the book, but is able to process large books quickly.

It generates reference locations that are independent of render size and can provide percentage locations of given CFI's in an epub.

Once the locations have been loaded or generated, the "relocated" event will include location information when the visible area changes.

A more fully feature example (with local storage) is at examples/locations.html.

Hooks

The API for hooks has changed to registering function on a specific hookable event.

So the example hook changed from:

EPUBJS.Hooks.register("beforeChapterDisplay").example = function(callback, renderer){
  // ...
}

To registering onto the content hook:

rendition.hooks.content.register(function(contents, view) {
  // ...
})

Rather than a callback, registered tasks on a hook can now return a promise to block until they are finished.

Additional hooks are listed in the Readme.