epub.js/documentation/md/API.md

ePub

Creates a new Book

Parameters

• url (string | ArrayBuffer) URL, Path or ArrayBuffer
• options object to pass to the book

Examples

ePub("/path/to/book.epub", {})

Returns Book a new Book object

register

register plugins

manager

register a new view manager

view

register a new view

Book

Creates a new Book

Parameters

• url string
• options object
  • options.requestMethod method a request function to use instead of the default
  • options.requestCredentials [boolean] send the xhr request withCredentials (optional, default undefined)
  • options.requestHeaders [object] send the xhr request headers (optional, default undefined)
  • options.encoding [string] optional to pass 'binary' or base64' for archived Epubs (optional, default binary)
  • options.replacements [string] use base64, blobUrl, or none for replacing assets in archived Epubs (optional, default base64)

Examples

new Book("/path/to/book.epub", {})

new Book({ replacements: "blobUrl" })

Returns Book

opened

Properties

• opened promise returns after the book is loaded

spine

Properties

• spine Spine

locations

Properties

• locations Locations

navigation

Properties

• navigation Navigation

pageList

Properties

• pagelist PageList

open

Open a epub or url

Parameters

• input string URL, Path or ArrayBuffer
• what [string] to force opening

Examples

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

Returns Promise of when the book has been loaded

load

Load a resource from the Book

Parameters

• path string path to the resource to load

Returns Promise returns a promise with the requested resource

resolve

Resolve a path to it's absolute position in the Book

Parameters

• path string
• absolute [boolean] force resolving the full URL

Returns string the resolved path string

section

Alias for book.spine.get

Parameters

• target string

renderTo

Sugar to render a book

Parameters

• element element element to add the views to
• options [object]

Returns Rendition

setRequestCredentials

Set if request should use withCredentials

Parameters

• credentials boolean

setRequestHeaders

Set headers request should use

Parameters

• headers object

coverUrl

Get the cover url

Returns string coverUrl

range

Find a DOM Range for a given CFI Range

Parameters

• cfiRange EpubCFI a epub cfi range

Returns Range

key

Generates the Book Key using the identifer in the manifest or other string provided

Parameters

• identifier [string] to use instead of metadata identifier

Returns string key

Url

creates a uri object

Parameters

• urlString string a url string (relative or absolute)
• baseString [string] optional base for the url, default to window.location.href

Returns object url

Spine

A collection of Spine Items

unpack

Unpack items from a opf into spine items

Parameters

• _package Package
• resolver method URL resolver

get

Get an item from the spine

Parameters

• target

Examples

spine.get();

spine.get(1);

spine.get("chap1.html");

spine.get("#id1234");

Returns Section section

each

Loop over the Sections in the Spine

Returns method forEach

Section

Represents a Section of the Book In most books this is equivelent to a Chapter

Parameters

• item object The spine item representing the section
• hooks object hooks for serialize and content

load

Load the section from its url

Parameters

• _request method a request method to use for loading

Returns document a promise with the xml document

render

Render the contents of a section

Parameters

• _request method a request method to use for loading

Returns string output a serialized XML Document

find

Find a string in a section TODO: need reimplementation from v0.2

Parameters

• query string [description]

Returns [type] [description]

reconcileLayoutSettings

Reconciles the current chapters layout properies with the global layout properities.

Parameters

• global object The globa layout settings object, chapter properties string

Returns object layoutProperties Object with layout properties

cfiFromRange

Get a CFI from a Range in the Section

Parameters

• _range range

Returns string cfi an EpubCFI string

cfiFromElement

Get a CFI from an Element in the Section

Parameters

• el element

Returns string cfi an EpubCFI string

Locations

Find Locations for a Book

Parameters

• spine Spine
• request request

generate

Load all of sections in the book to generate locations

Parameters

• chars int how many chars to split on

Returns object locations

Container

Handles Parsing and Accessing an Epub Container

Parameters

• containerDocument [document] xml document

parse

Parse the Container XML

Parameters

• containerDocument document

Packaging

Open Packaging Format Parser

Parameters

• packageDocument document OPF XML

parse

Parse OPF XML

Parameters

• packageDocument document OPF XML

Returns object parsed package parts

parseSpine

Parse Spine

Parameters

• spineXml document
• manifest Packaging.manifest

Returns object spine

findCoverPath

Find the Cover Path Fallback for Epub 2.0

Parameters

• packageXml document

Returns string href

Navigation

Navigation Parser

Parameters

• xml document navigation html / xhtml / ncx

parse

Parse out the navigation items

Parameters

• xml document navigation html / xhtml / ncx

get

Get an item from the navigation

Parameters

• target string

Returns object navItems

Resources

Handle Package Resources

Parameters

• manifest Manifest
• options [object]
  • options.archive [Archive]
  • options.resolver [method]

replacements

Create blob urls for all the assets

Parameters

• archive Archive
• resolver resolver Url resolver

Returns Promise returns replacement urls

relativeTo

Resolve all resources URLs relative to an absolute URL

Parameters

• absolute string to be resolved to
• resolver [resolver]

Returns Array<string> array with relative Urls

get

Get a URL for a resource

Parameters

• path string

Returns string url

PageList

Page List Parser

Parameters

• xml [document]

parse

Parse PageList Xml

Parameters

• xml document

addCFIs

Replace HREFs with CFI TODO: implement getting CFI from Href

pageFromCfi

Get a PageList result from a EpubCFI

Parameters

• cfi string EpubCFI String

Returns string page

cfiFromPage

Get an EpubCFI from a Page List Item

Parameters

• pg string

Returns string cfi

pageFromPercentage

Get a Page from Book percentage

Parameters

• percent number

Returns string page

percentageFromPage

Returns a value between 0 - 1 corresponding to the location of a page

Parameters

• pg int the page

Returns number percentage

percentageFromCfi

Returns a value between 0 - 1 corresponding to the location of a cfi

Parameters

• cfi string EpubCFI String

Returns number percentage

Archive

Handles Unzipping a requesting files from an Epub Archive

open

Open an archive

Parameters

• input binary
• isBase64 boolean tells JSZip if the input data is base64 encoded

Returns Promise zipfile

openUrl

Load and Open an archive

Parameters

• zipUrl string
• isBase64 boolean tells JSZip if the input data is base64 encoded

Returns Promise zipfile

request

Request

Parameters

• url string a url to request from the archive
• type [string] specify the type of the returned result

Returns Promise

getBlob

Get a Blob from Archive by Url

Parameters

• url string
• mimeType [string]

Returns Blob

getText

Get Text from Archive by Url

Parameters

• url string
• encoding [string]

Returns string

getBase64

Get a base64 encoded result from Archive by Url

Parameters

• url string
• mimeType [string]

Returns string base64 encoded

createUrl

Create a Url from an unarchived item

Parameters

• url string
• options
  • options.base64 [object] use base64 encoding or blob url

Returns Promise url promise with Url string

revokeUrl

Revoke Temp Url for a achive item

Parameters

• url string url of the item in the archive

EpubCFI

EPUB CFI spec: http://www.idpf.org/epub/linking/cfi/epub-cfi.html

Implements:

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

Does Not Implement:

• Temporal Offset (~)
• Spatial Offset (@)
• Temporal-Spatial Offset (~ + @)
• Text Location Assertion ([)

Parameters

• cfiFrom
• base
• ignoreClass

content

Properties

• hooks.content method

Rendition

[Rendition description]

Parameters

• book Book
• options object
  • options.width int
  • options.height int
  • options.ignoreClass string
  • options.manager string
  • options.view string
  • options.layout string
  • options.spread string
  • options.minSpreadWidth int overridden by spread: none (never) / both (always)

hooks

Adds Hook methods to the Rendition prototype

Properties

• hooks Hook

setManager

Set the manager function

Parameters

• manager function

requireManager

Require the manager from passed string, or as a function

Parameters

• manager (string | function) [description]

Returns method

requireView

Require the view from passed string, or as a function

Parameters

• view (string | function)

Returns view

start

Start the rendering

Returns Promise rendering has started

attachTo

Call to attach the container to an element in the dom Container must be attached before rendering can begin

Parameters

• element element to attach to

Returns Promise

display

Display a point in the book The request will be added to the rendering Queue, so it will wait until book is opened, rendering started and all other rendering tasks have finished to be called.

Parameters

• target string Url or EpubCFI

Returns Promise

moveTo

Move the Rendition to a specific offset Usually you would be better off calling display()

Parameters

• offset object

next

Go to the next "page" in the rendition

Returns Promise

prev

Go to the previous "page" in the rendition

Returns Promise

flow

Adjust the flow of the rendition to paginated or scrolled (scrolled-continuous vs scrolled-doc are handled by different view managers)

Parameters

• flow string

layout

Adjust the layout of the rendition to reflowable or pre-paginated

Parameters

• settings object

spread

Adjust if the rendition uses spreads

Parameters

• spread string none | auto (TODO: implement landscape, portrait, both)
• min int min width to use spreads at

currentLocation

Get the Current Location CFI

Returns EpubCFI location (may be a promise)

destroy

Remove and Clean Up the Rendition

range

Get a Range from a Visible CFI

Parameters

• cfi string EpubCfi String
• ignoreClass string

Returns range

adjustImages

Hook to adjust images to fit in columns

Parameters

• view View

Hook

Hooks allow for injecting functions that must all complete in order before finishing They will execute in parallel but all must finish before continuing Functions may return a promise if they are asycn.

Parameters

• context any scope of this

Examples

this.content = new EPUBJS.Hook(this);

register

Adds a function to be run before a hook completes

Examples

this.content.register(function(){...});

trigger

Triggers a hook to run all functions

Examples

this.content.trigger(args).then(function(){...});

Queue

Queue for handling tasks one at a time

Parameters

• context scope what this will resolve to in the tasks

enqueue

Add an item to the queue

Returns Promise

dequeue

Run one item

Returns Promise

run

Run all tasks sequentially, at convince

Returns Promise

flush

Flush all, as quickly as possible

Returns Promise

clear

Clear all items in wait

length

Get the number of tasks in the queue

Returns int tasks

pause

Pause a running queue

Layout

Figures out the CSS to apply for a layout

Parameters

• settings object
  • settings.spread [string]

flow

Switch the flow between paginated and scrolled

Parameters

• flow string paginated | scrolled

spread

Switch between using spreads or not, and set the width at which they switch to single.

Parameters

• spread string true | false
• min boolean integer in pixels

calculate

Calculate the dimensions of the pagination

Parameters

• _width number [description]
• _height number [description]
• _gap number [description]

format

Apply Css to a Document

Parameters

• contents Contents

Returns [Promise]

count

Count number of pages

Parameters

• totalWidth number

Returns number spreads

Returns number pages