epub.js

The EpubCFI class handles the parsing and creation of EPUB Canonical Fragment Identifiers (CFIs), which are used to link to specific locations within an EPUB document.

It supports:

• Character Offset: e.g., epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/2/1:3)
• Simple Ranges: e.g., epubcfi(/6/4[chap01ref]!/4[body01]/10[para05],/2/1:1,/3:4)

Note that it does not implement Temporal Offset (~), Spatial Offset (@), Temporal-Spatial Offset (~ + @), or Text Location Assertion (\[).

Hooks allow you to inject functions that must all complete (in parallel) before a process finishes. Functions can return a Promise if they are asynchronous.

Usage Pattern:

1. Create a hook: this.content = new EPUBJS.Hook(this);
2. Register a function: this.content.register(function(){...});
3. Trigger the hook: this.content.trigger(args).then(function(){...});

To run the project locally or build it for distribution, ensure you have Node.js installed.

Local Development

• Install dependencies: npm install
• Run the reader: npm start
• Run tests: npm test

Building for Distribution

Builds are minified using Webpack and Babel.

• Generate a new build: npm run prepare
• Continuous build (watch mode): npm run watch

To use Epub.js with archived .epub files, you must include JSZip before including epub.js.

1. Include JSZip via CDN.
2. Include the minified epub.min.js from your build folder.
3. Define an HTML element (e.g., a div) to serve as the rendering area.
4. Initialize the book using ePub() and render it using book.renderTo().

<!-- 1. Include JSZip first -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/jszip/3.1.5/jszip.min.js"></script>

<!-- 2. Include epub.js -->
<script src="../dist/epub.min.js"></script>

<!-- 3. Set up a element to render to -->
<div id="area"></div>

<!-- 4. Create the new ePub and render -->
<script>
  var book = ePub("url/to/book/package.opf");
  var rendition = book.renderTo("area", {width: 600, height: 400});
  var displayed = rendition.display();
</script>

When creating a Book instance, you can pass an options object to control how the EPUB is loaded and how assets are handled:

• requestMethod: A custom request function.
• requestCredentials: Boolean to indicate if the XHR request should use withCredentials (default: undefined).
• requestHeaders: An object containing custom XHR request headers.
• encoding: Set to 'binary' or 'base64' for archived EPUBs (default: 'binary').
• replacements: Strategy for replacing assets in archived EPUBs. Options: 'base64', 'blobUrl', or 'none' (default: 'none').
• canonical: An optional function to determine canonical URLs for a path.
• openAs: A string to force the input type.

new Book({ replacements: "blobUrl" })

The flow option in renderTo determines how the content is laid out. It defaults to paginated if not specified (based on OPF settings).

• auto: Uses settings from the EPUB's OPF file (defaults to paginated).
• paginated: Forces a paginated layout.
• scrolled-doc: Forces a scrolled document layout.

The Locations API allows you to manage reading progress and convert between different positioning formats (CFI, percentage, and location index).

• generate(chars): Loads all sections in the book to generate a location map. chars defines how many characters to split on.
• locationFromCfi(cfi): Returns a location index (number) from an EpubCFI.
• cfiFromLocation(loc): Returns an EpubCFI from a location index.
• percentageFromCfi(cfi): Returns a percentage (0-1) from an EpubCFI.
• cfiFromPercentage(percentage): Returns an EpubCFI from a percentage (0-1).
• currentLocation: Get or set the current location index.
• save(): Returns a JSON representation of the locations.
• load(locations): Loads locations from a JSON object.

The book.open(input, what) method loads an EPUB from a URL, path, or ArrayBuffer. The what parameter allows you to force the input type. Supported types include: "binary", "base64", "epub", "opf", "json", and "directory".

book.open("/path/to/book.epub")

Use the spread method to control when the viewer uses double-page spreads.

Parameters:

• spread (string): 'none' | 'always' | 'auto'
• min (number): An integer representing the minimum width in pixels at which it switches to single page.

Returns: A boolean indicating if spread is active.