From 46800b05b64f1e143323e65c7f218a5254fcda1b Mon Sep 17 00:00:00 2001 From: Fred Chasen Date: Wed, 8 Nov 2017 19:27:58 -0800 Subject: [PATCH] Add layout event and forceEvenPages for default manager --- documentation/md/API.md | 1686 ++++++++++++++++++++++++++---- src/layout.js | 73 +- src/managers/continuous/index.js | 3 +- src/managers/default/index.js | 7 +- src/managers/views/iframe.js | 28 +- src/rendition.js | 27 + src/utils/constants.js | 6 +- src/utils/core.js | 2 +- 8 files changed, 1568 insertions(+), 264 deletions(-) diff --git a/documentation/md/API.md b/documentation/md/API.md index b532e8b..7524f5a 100644 --- a/documentation/md/API.md +++ b/documentation/md/API.md @@ -1,6 +1,6 @@ -# ePub +## ePub Creates a new Book @@ -17,31 +17,43 @@ ePub("/path/to/book.epub", {}) Returns **[Book](#book)** a new Book object -## register +### register -register plugins +Register Managers and Views -### manager +#### manager register a new view manager -### view +**Parameters** + +- `name` +- `manager` + +#### view register a new view -# Book +**Parameters** -Creates a new Book +- `name` +- `view` + +## Book + +An Epub representation with methods for the loading, parsing and manipulation +of its contents. **Parameters** -- `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** -- `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** - - `options.requestMethod` **method** a request function to use instead of the default - - `options.requestCredentials` **\[[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** send the xhr request withCredentials (optional, default `undefined`) - - `options.requestHeaders` **\[[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** send the xhr request headers (optional, default `undefined`) - - `options.encoding` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** optional to pass 'binary' or base64' for archived Epubs (optional, default `binary`) - - `options.replacements` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** use base64, blobUrl, or none for replacing assets in archived Epubs (optional, default `base64`) +- `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** +- `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** + - `options.requestMethod` **method?** a request function to use instead of the default + - `options.requestCredentials` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** send the xhr request withCredentials (optional, default `undefined`) + - `options.requestHeaders` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** send the xhr request headers (optional, default `undefined`) + - `options.encoding` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** optional to pass 'binary' or base64' for archived Epubs (optional, default `binary`) + - `options.replacements` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** use base64, blobUrl, or none for replacing assets in archived Epubs (optional, default `none`) + - `options.canonical` **method?** optional function to determine canonical urls for a path **Examples** @@ -55,44 +67,14 @@ new Book({ replacements: "blobUrl" }) Returns **[Book](#book)** -## opened - -**Properties** - -- `opened` **[promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns after the book is loaded - -## spine - -**Properties** - -- `spine` **[Spine](#spine)** - -## locations - -**Properties** - -- `locations` **[Locations](#locations)** - -## navigation - -**Properties** - -- `navigation` **[Navigation](#navigation)** - -## pageList - -**Properties** - -- `pagelist` **[PageList](#pagelist)** - -## open +### open Open a epub or url **Parameters** -- `input` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** URL, Path or ArrayBuffer -- `what` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** to force opening +- `input` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer))** Url, Path or ArrayBuffer +- `what` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** force opening as a certain type (optional, default `"binary","base64","epub","opf","json","directory"`) **Examples** @@ -102,7 +84,7 @@ book.open("/path/to/book.epub") Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** of when the book has been loaded -## load +### load Load a resource from the Book @@ -112,37 +94,50 @@ Load a resource from the Book Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns a promise with the requested resource -## resolve +### resolve Resolve a path to it's absolute position in the Book **Parameters** - `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** -- `absolute` **\[[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** force resolving the full URL +- `absolute` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** force resolving the full URL Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** the resolved path string -## section +### canonical -Alias for book.spine.get +Get a canonical link to a path + +**Parameters** + +- `path` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** the canonical path string + +### section + +Gets a Section of the Book from the Spine +Alias for `book.spine.get` **Parameters** - `target` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** -## renderTo +Returns **[Section](#section)** -Sugar to render a book +### renderTo + +Sugar to render a book to an element **Parameters** -- `element` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** element to add the views to -- `options` **\[[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** +- `element` **([element](https://developer.mozilla.org/en-US/docs/Web/API/Element) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** element or string to add a rendition to +- `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Returns **[Rendition](#rendition)** -## setRequestCredentials +### setRequestCredentials Set if request should use withCredentials @@ -150,7 +145,7 @@ Set if request should use withCredentials - `credentials` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** -## setRequestHeaders +### setRequestHeaders Set headers request should use @@ -158,13 +153,13 @@ Set headers request should use - `headers` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** -## coverUrl +### coverUrl Get the cover url Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** coverUrl -## range +### getRange Find a DOM Range for a given CFI Range @@ -174,33 +169,149 @@ Find a DOM Range for a given CFI Range Returns **[Range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input)** -## key +### key Generates the Book Key using the identifer in the manifest or other string provided **Parameters** -- `identifier` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** to use instead of metadata identifier +- `identifier` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** to use instead of metadata identifier Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** key -# Url +### destroy -creates a uri object +Destroy the Book and all associated objects + +### opened + +### spine + +Type: [Spine](#spine) + +### locations + +Type: [Locations](#locations) + +### navigation + +Type: [Navigation](#navigation) + +### pagelist + +Type: [PageList](#pagelist) + +## Url + +creates a Url object for parsing and manipulation of a url string **Parameters** - `urlString` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a url string (relative or absolute) -- `baseString` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** optional base for the url, +- `baseString` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** optional base for the url, default to window.location.href -Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** url +### path -# Spine +Returns **[Path](#path)** + +### resolve + +Resolves a relative path to a absolute url + +**Parameters** + +- `what` + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** url + +### relative + +Resolve a path relative to the url + +**Parameters** + +- `what` + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** path + +### toString + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +## Path + +Creates a Path object for parsing and manipulation of a path strings + +Uses a polyfill for Nodejs path: + +**Parameters** + +- `pathString` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a url string (relative or absolute) + +### parse + +Parse the path: + +**Parameters** + +- `what` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + +### isAbsolute + +**Parameters** + +- `what` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + +### isDirectory + +Check if path ends with a directory + +**Parameters** + +- `what` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + +### resolve + +Resolve a path against the directory of the Path + + + +**Parameters** + +- `what` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** resolved + +### relative + +Resolve a path relative to the directory of the Path + + + +**Parameters** + +- `what` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** relative + +### toString + +Return the path string + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** path + +## Spine A collection of Spine Items -## unpack +### unpack Unpack items from a opf into spine items @@ -208,14 +319,15 @@ Unpack items from a opf into spine items - `_package` **Package** - `resolver` **method** URL resolver +- `canonical` -## get +### get Get an item from the spine **Parameters** -- `target` +- `target` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) | int)?** **Examples** @@ -237,15 +349,16 @@ spine.get("#id1234"); Returns **[Section](#section)** section -## each +### each Loop over the Sections in the Spine Returns **method** forEach -# Section +## Section Represents a Section of the Book + In most books this is equivelent to a Chapter **Parameters** @@ -253,7 +366,7 @@ In most books this is equivelent to a Chapter - `item` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** The spine item representing the section - `hooks` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** hooks for serialize and content -## load +### load Load the section from its url @@ -263,7 +376,7 @@ Load the section from its url Returns **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** a promise with the xml document -## render +### render Render the contents of a section @@ -273,18 +386,17 @@ Render the contents of a section Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** output a serialized XML Document -## find +### find Find a string in a section -TODO: need reimplementation from v0.2 **Parameters** -- `query` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** [description] +- `_query` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The query string to find -Returns **\[type]** [description] +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** A list of matches, with form {cfi, excerpt} -## reconcileLayoutSettings +### reconcileLayoutSettings Reconciles the current chapters layout properies with the global layout properities. @@ -295,7 +407,7 @@ the global layout properities. Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** layoutProperties Object with layout properties -## cfiFromRange +### cfiFromRange Get a CFI from a Range in the Section @@ -305,7 +417,7 @@ Get a CFI from a Range in the Section Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** cfi an EpubCFI string -## cfiFromElement +### cfiFromElement Get a CFI from an Element in the Section @@ -315,7 +427,11 @@ Get a CFI from an Element in the Section Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** cfi an EpubCFI string -# Locations +### unload + +Unload the section document + +## Locations Find Locations for a Book @@ -323,8 +439,9 @@ Find Locations for a Book - `spine` **[Spine](#spine)** - `request` **[request](https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/request)** +- `pause` -## generate +### generate Load all of sections in the book to generate locations @@ -334,15 +451,96 @@ Load all of sections in the book to generate locations Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** locations -# Container +### locationFromCfi + +Get a location from an EpubCFI + +**Parameters** + +- `cfi` **[EpubCFI](#epubcfi)** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +### percentageFromCfi + +Get a percentage position in locations from an EpubCFI + +**Parameters** + +- `cfi` **[EpubCFI](#epubcfi)** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +### percentageFromLocation + +Get a percentage position from a location index + +**Parameters** + +- `loc` +- `location` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +### cfiFromLocation + +Get an EpubCFI from location index + +**Parameters** + +- `loc` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +Returns **[EpubCFI](#epubcfi)** cfi + +### cfiFromPercentage + +Get an EpubCFI from location percentage + +**Parameters** + +- `percentage` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +Returns **[EpubCFI](#epubcfi)** cfi + +### load + +Load locations from JSON + +**Parameters** + +- `locations` **[json](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)** + +### save + +Save locations to JSON + +Returns **[json](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)** + +### currentLocation + +Get the current location + +### currentLocation + +Set the current location + +**Parameters** + +- `curr` + +### length + +Locations length + +## Container Handles Parsing and Accessing an Epub Container **Parameters** -- `containerDocument` **\[[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)]** xml document +- `containerDocument` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)?** xml document -## parse +### parse Parse the Container XML @@ -350,7 +548,7 @@ Parse the Container XML - `containerDocument` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** -# Packaging +## Packaging Open Packaging Format Parser @@ -358,7 +556,7 @@ Open Packaging Format Parser - `packageDocument` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** OPF XML -## parse +### parse Parse OPF XML @@ -368,7 +566,7 @@ Parse OPF XML Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** parsed package parts -## parseSpine +### parseSpine Parse Spine @@ -379,7 +577,7 @@ Parse Spine Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** spine -## findCoverPath +### findCoverPath Find the Cover Path @@ -391,7 +589,18 @@ Fallback for Epub 2.0 Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** href -# Navigation +### load + +Load JSON Manifest + +**Parameters** + +- `json` +- `packageDocument` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** OPF XML + +Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** parsed package parts + +## Navigation Navigation Parser @@ -399,7 +608,7 @@ Navigation Parser - `xml` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** navigation html / xhtml / ncx -## parse +### parse Parse out the navigation items @@ -407,7 +616,7 @@ Parse out the navigation items - `xml` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** navigation html / xhtml / ncx -## get +### get Get an item from the navigation @@ -417,7 +626,36 @@ Get an item from the navigation Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** navItems -# Resources +### landmark + +Get a landmark by type +List of types: + +**Parameters** + +- `type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** landmarkItems + +### load + +Load Spine Items + +**Parameters** + +- `json` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the items to be loaded + +### forEach + +forEach pass through + +**Parameters** + +- `fn` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** function to run on each item + +Returns **method** forEach loop + +## Resources Handle Package Resources @@ -428,18 +666,13 @@ Handle Package Resources - `options.archive` **\[[Archive](#archive)]** - `options.resolver` **\[method]** -## replacements +### replacements Create blob urls for all the assets -**Parameters** - -- `archive` **[Archive](#archive)** -- `resolver` **resolver** Url resolver - Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** returns replacement urls -## relativeTo +### relativeTo Resolve all resources URLs relative to an absolute URL @@ -450,7 +683,7 @@ Resolve all resources URLs relative to an absolute URL Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** array with relative Urls -## get +### get Get a URL for a resource @@ -460,15 +693,27 @@ Get a URL for a resource Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** url -# PageList +### substitute + +Substitute urls in content, with replacements, +relative to a url if provided + +**Parameters** + +- `content` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** +- `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** url to resolve to + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** content with urls substituted + +## PageList Page List Parser **Parameters** -- `xml` **\[[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)]** +- `xml` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)?** -## parse +### parse Parse PageList Xml @@ -476,12 +721,7 @@ Parse PageList Xml - `xml` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** -## addCFIs - -Replace HREFs with CFI -TODO: implement getting CFI from Href - -## pageFromCfi +### pageFromCfi Get a PageList result from a EpubCFI @@ -491,7 +731,7 @@ Get a PageList result from a EpubCFI Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** page -## cfiFromPage +### cfiFromPage Get an EpubCFI from a Page List Item @@ -501,7 +741,7 @@ Get an EpubCFI from a Page List Item Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** cfi -## pageFromPercentage +### pageFromPercentage Get a Page from Book percentage @@ -511,7 +751,7 @@ Get a Page from Book percentage Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** page -## percentageFromPage +### percentageFromPage Returns a value between 0 - 1 corresponding to the location of a page @@ -521,7 +761,7 @@ Returns a value between 0 - 1 corresponding to the location of a page Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** percentage -## percentageFromCfi +### percentageFromCfi Returns a value between 0 - 1 corresponding to the location of a cfi @@ -531,11 +771,11 @@ Returns a value between 0 - 1 corresponding to the location of a cfi Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** percentage -# Archive +## Archive Handles Unzipping a requesting files from an Epub Archive -## open +### open Open an archive @@ -546,7 +786,7 @@ Open an archive Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** zipfile -## openUrl +### openUrl Load and Open an archive @@ -557,51 +797,51 @@ Load and Open an archive Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** zipfile -## request +### request -Request +Request a url from the archive **Parameters** - `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a url to request from the archive -- `type` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** specify the type of the returned result +- `type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** specify the type of the returned result Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## getBlob +### getBlob Get a Blob from Archive by Url **Parameters** - `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** -- `mimeType` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** +- `mimeType` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Returns **[Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)** -## getText +### getText Get Text from Archive by Url **Parameters** - `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** -- `encoding` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** +- `encoding` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** -## getBase64 +### getBase64 Get a base64 encoded result from Archive by Url **Parameters** - `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** -- `mimeType` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** +- `mimeType` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** base64 encoded -## createUrl +### createUrl Create a Url from an unarchived item @@ -609,11 +849,10 @@ Create a Url from an unarchived item - `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** - `options` - - `options.base64` **\[[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** use base64 encoding or blob url Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** url promise with Url string -## revokeUrl +### revokeUrl Revoke Temp Url for a achive item @@ -621,60 +860,28 @@ Revoke Temp Url for a achive item - `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** url of the item in the archive -# EpubCFI +## Rendition -EPUB CFI spec: - -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] +Displays an Epub as a series of Views for each Section. +Requires Manager and View class to handle specifics of rendering +the section contetn. **Parameters** - `book` **[Book](#book)** -- `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** - - `options.width` **int** - - `options.height` **int** - - `options.ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** - - `options.manager` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** - - `options.view` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** - - `options.layout` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** - - `options.spread` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** - - `options.minSpreadWidth` **int** overridden by spread: none (never) / both (always) +- `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** + - `options.width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** + - `options.height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** + - `options.ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** class for the cfi parser to ignore + - `options.manager` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) \| [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** (optional, default `'default'`) + - `options.view` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function))** (optional, default `'iframe'`) + - `options.layout` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** layout to force + - `options.spread` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** force spread value + - `options.minSpreadWidth` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** overridden by spread: none (never) / both (always) + - `options.stylesheet` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** url of stylesheet to be injected + - `options.script` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** url of script to be injected -## hooks - -Adds Hook methods to the Rendition prototype - -**Properties** - -- `hooks` **[Hook](#hook)** - -## setManager +### setManager Set the manager function @@ -682,33 +889,33 @@ Set the manager function - `manager` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** -## requireManager +### requireManager -Require the manager from passed string, or as a function +Require the manager from passed string, or as a class function **Parameters** -- `manager` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function))** [description] +- `manager` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** [description] Returns **method** -## requireView +### requireView -Require the view from passed string, or as a function +Require the view from passed string, or as a class function **Parameters** -- `view` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function))** +- `view` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** Returns **view** -## start +### start Start the rendering Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** rendering has started -## attachTo +### attachTo Call to attach the container to an element in the dom Container must be attached before rendering can begin @@ -719,7 +926,7 @@ Container must be attached before rendering can begin Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## display +### display Display a point in the book The request will be added to the rendering Queue, @@ -732,7 +939,7 @@ and all other rendering tasks have finished to be called. Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## moveTo +### moveTo Move the Rendition to a specific offset Usually you would be better off calling display() @@ -741,19 +948,32 @@ Usually you would be better off calling display() - `offset` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** -## next +### resize + +Trigger a resize of the views + +**Parameters** + +- `width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** +- `height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** + +### clear + +Clear all rendered views + +### next Go to the next "page" in the rendition Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## prev +### prev Go to the previous "page" in the rendition Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## flow +### flow Adjust the flow of the rendition to paginated or scrolled (scrolled-continuous vs scrolled-doc are handled by different view managers) @@ -762,7 +982,7 @@ Adjust the flow of the rendition to paginated or scrolled - `flow` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** -## layout +### layout Adjust the layout of the rendition to reflowable or pre-paginated @@ -770,7 +990,7 @@ Adjust the layout of the rendition to reflowable or pre-paginated - `settings` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** -## spread +### spread Adjust if the rendition uses spreads @@ -779,17 +999,29 @@ Adjust if the rendition uses spreads - `spread` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** none | auto (TODO: implement landscape, portrait, both) - `min` **int** min width to use spreads at -## currentLocation +### direction -Get the Current Location CFI +Adjust the direction of the rendition -Returns **[EpubCFI](#epubcfi)** location (may be a promise) +**Parameters** -## destroy +- `dir` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +### reportLocation + +Report the current location + +### currentLocation + +Get the Current Location object + +Returns **(displayedLocation | [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise))** location (may be a promise) + +### destroy Remove and Clean Up the Rendition -## range +### getRange Get a Range from a Visible CFI @@ -800,15 +1032,62 @@ Get a Range from a Visible CFI Returns **[range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input)** -## adjustImages +### getContents -Hook to adjust images to fit in columns +Get the Contents object of each rendered view -**Parameters** +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Contents](#contents)>** -- `view` **View** +### views -# Hook +Get the views member from the manager + +Returns **Views** + +### hooks + +Adds Hook methods to the Rendition prototype + +Type: [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) + +### themes + +Type: [Themes](#themes) + +### annotations + +Type: [Annotations](#annotations) + +### location + +A Rendered Location Range + +**Properties** + +- `start` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + - `start.index` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + - `start.href` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + - `start.displayed` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + - `start.displayed.page` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + - `start.displayed.total` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + - `start.cfi` **[EpubCFI](#epubcfi)** + - `start.location` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + - `start.percentage` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `end` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + - `end.index` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + - `end.href` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + - `end.displayed` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + - `end.displayed.page` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + - `end.displayed.total` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + - `end.cfi` **[EpubCFI](#epubcfi)** + - `end.location` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + - `end.percentage` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `atStart` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** +- `atEnd` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + +### started + +## 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 @@ -824,7 +1103,7 @@ Functions may return a promise if they are asycn. this.content = new EPUBJS.Hook(this); ``` -## register +### register Adds a function to be run before a hook completes @@ -834,7 +1113,7 @@ Adds a function to be run before a hook completes this.content.register(function(){...}); ``` -## trigger +### trigger Triggers a hook to run all functions @@ -844,7 +1123,7 @@ Triggers a hook to run all functions this.content.trigger(args).then(function(){...}); ``` -# Queue +## Queue Queue for handling tasks one at a time @@ -852,54 +1131,61 @@ Queue for handling tasks one at a time - `context` **scope** what this will resolve to in the tasks -## enqueue +### enqueue Add an item to the queue Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## dequeue +### dequeue Run one item Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## run +### run Run all tasks sequentially, at convince Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## flush +### flush Flush all, as quickly as possible Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## clear +### clear Clear all items in wait -## length +### length Get the number of tasks in the queue Returns **int** tasks -## pause +### pause Pause a running queue -# Layout +### stop -Figures out the CSS to apply for a layout +End the queue + +## Layout + +Figures out the CSS values to apply for a layout **Parameters** - `settings` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** - - `settings.spread` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** + - `settings.layout` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** (optional, default `'reflowable'`) + - `settings.spread` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + - `settings.minSpreadWidth` **int** (optional, default `800`) + - `settings.evenSpreads` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** (optional, default `false`) -## flow +### flow Switch the flow between paginated and scrolled @@ -907,7 +1193,7 @@ Switch the flow between paginated and scrolled - `flow` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** paginated | scrolled -## spread +### spread Switch between using spreads or not, and set the width at which they switch to single. @@ -917,7 +1203,7 @@ width at which they switch to single. - `spread` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** true | false - `min` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** integer in pixels -## calculate +### calculate Calculate the dimensions of the pagination @@ -927,24 +1213,972 @@ Calculate the dimensions of the pagination - `_height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** [description] - `_gap` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** [description] -## format +### format Apply Css to a Document **Parameters** -- `contents` **Contents** +- `contents` **[Contents](#contents)** -Returns **\[[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)]** +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** -## count +### count Count number of pages **Parameters** -- `totalWidth` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `totalLength` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `pageLength` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** -Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** spreads +Returns **{spreads: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), pages: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)}** -Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** pages +## Themes + +Themes to apply to displayed content + +**Parameters** + +- `rendition` **[Rendition](#rendition)** + +### register + +Add themes to be used by a rendition + +**Examples** + +```javascript +themes.register("light", "http://example.com/light.css") +``` + +```javascript +themes.register("light", { "body": { "color": "purple"}}) +``` + +```javascript +themes.register({ "light" : {...}, "dark" : {...}}) +``` + +### default + +Add a default theme to be used by a rendition + +**Parameters** + +- `theme` **([object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** + +**Examples** + +```javascript +themes.register("http://example.com/default.css") +``` + +```javascript +themes.register({ "body": { "color": "purple"}}) +``` + +### fontSize + +Adjust the font size of a rendition + +**Parameters** + +- `size` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +### font + +Adjust the font-family of a rendition + +**Parameters** + +- `f` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +## Annotations + +Handles managing adding & removing Annotations + +**Parameters** + +- `rendition` **[Rendition](#rendition)** + +### add + +Add an annotation to store + +**Parameters** + +- `type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of annotation to add: "highlight", "underline", "mark" +- `cfiRange` **[EpubCFI](#epubcfi)** EpubCFI range to attach annotation to +- `data` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data to assign to annotation +- `cb` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Callback after annotation is added + +Returns **[Annotation](#annotation)** annotation + +### remove + +Remove an annotation from store + +**Parameters** + +- `cfiRange` **[EpubCFI](#epubcfi)** EpubCFI range the annotation is attached to +- `type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of annotation to add: "highlight", "underline", "mark" + +### highlight + +Add a highlight to the store + +**Parameters** + +- `cfiRange` **[EpubCFI](#epubcfi)** EpubCFI range to attach annotation to +- `data` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data to assign to annotation +- `cb` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Callback after annotation is added + +### underline + +Add a underline to the store + +**Parameters** + +- `cfiRange` **[EpubCFI](#epubcfi)** EpubCFI range to attach annotation to +- `data` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data to assign to annotation +- `cb` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Callback after annotation is added + +### mark + +Add a mark to the store + +**Parameters** + +- `cfiRange` **[EpubCFI](#epubcfi)** EpubCFI range to attach annotation to +- `data` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data to assign to annotation +- `cb` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Callback after annotation is added + +### each + +iterate over annotations in the store + +### show + +[Not Implemented] Show annotations + +### hide + +[Not Implemented] Hide annotations + +## Annotation + +Annotation object + +**Parameters** + +- `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + - `options.type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of annotation to add: "highlight", "underline", "mark" + - `options.cfiRange` **[EpubCFI](#epubcfi)** EpubCFI range to attach annotation to + - `options.data` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data to assign to annotation + - `options.sectionIndex` **int** Index in the Spine of the Section annotation belongs to + - `options.cb` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** Callback after annotation is added + +Returns **[Annotation](#annotation)** annotation + +### update + +Update stored data + +**Parameters** + +- `data` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + +### attach + +Add to a view + +**Parameters** + +- `view` **View** + +### detach + +Remove from a view + +**Parameters** + +- `view` **View** + +### text + +[Not Implemented] Get text of an annotation + +## EpubCFI + +Parsing and creation of EpubCFIs: + +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` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input) \| [Node](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling))?** +- `base` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))?** +- `ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** class to ignore when parsing DOM + +### parse + +Parse a cfi string to a CFI object representation + +**Parameters** + +- `cfiStr` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** cfi + +### toString + +Convert CFI to a epubcfi(...) string + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** epubcfi + +### compare + +Compare which of two CFIs is earlier in the text + +**Parameters** + +- `cfiOne` +- `cfiTwo` + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** First is earlier = 1, Second is earlier = -1, They are equal = 0 + +### fromRange + +Create a CFI object from a Range + +**Parameters** + +- `range` **[Range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input)** +- `base` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** +- `ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** cfi + +### fromNode + +Create a CFI object from a Node + +**Parameters** + +- `anchor` **[Node](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling)** +- `base` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** +- `ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** cfi + +### toRange + +Creates a DOM range representing a CFI + +**Parameters** + +- `_doc` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** document referenced in the base +- `ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +Returns **[Range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input)** + +### isCfiString + +Check if a string is wrapped with "epubcfi()" + +**Parameters** + +- `str` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + +### collapse + +Collapse a CFI Range to a single CFI Position + +**Parameters** + +- `toStart` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** (optional, default `false`) + +## Contents + +Handles DOM manipulation, queries and events for View contents + +**Parameters** + +- `doc` **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** Document +- `content` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** Parent Element (typically Body) +- `cfiBase` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Section component of CFIs +- `sectionIndex` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Index in Spine of Conntent's Section + +### width + +Get or Set width + +**Parameters** + +- `w` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** width + +### height + +Get or Set height + +**Parameters** + +- `h` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** height + +### contentWidth + +Get or Set width of the contents + +**Parameters** + +- `w` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** width + +### contentHeight + +Get or Set height of the contents + +**Parameters** + +- `h` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** height + +### textWidth + +Get the width of the text using Range + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** width + +### textHeight + +Get the height of the text using Range + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** height + +### scrollWidth + +Get documentElement scrollWidth + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** width + +### scrollHeight + +Get documentElement scrollHeight + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** height + +### overflow + +Set overflow css style of the contents + +**Parameters** + +- `overflow` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +### overflowX + +Set overflowX css style of the documentElement + +**Parameters** + +- `overflow` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +### overflowY + +Set overflowY css style of the documentElement + +**Parameters** + +- `overflow` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +### css + +Set Css styles on the contents element (typically Body) + +**Parameters** + +- `property` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** +- `value` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** +- `priority` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** set as "important" + +### viewport + +Get or Set the viewport element + +**Parameters** + +- `options` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** + - `options.width` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + - `options.height` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + - `options.scale` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + - `options.minimum` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + - `options.maximum` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + - `options.scalable` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +### root + +Get the documentElement + +Returns **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** documentElement + +### locationOf + +Get the location offset of a EpubCFI or an #id + +**Parameters** + +- `target` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [EpubCFI](#epubcfi))** +- `ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** for the cfi + +### addStylesheet + +Append a stylesheet link to the document head + +**Parameters** + +- `src` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** url + +### addStylesheetRules + +Append stylesheet rules to a generate stylesheet +Array: +Object: + +**Parameters** + +- `rules` **([array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** + +### addScript + +Append a script tag to the document head + +**Parameters** + +- `src` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** url + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** loaded + +### addClass + +Add a class to the contents container + +**Parameters** + +- `className` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +### removeClass + +Remove a class from the contents container + +**Parameters** + +- `className` +- `removeClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +### range + +Get a Dom Range from EpubCFI + +**Parameters** + +- `_cfi` **[EpubCFI](#epubcfi)** +- `ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +Returns **[Range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input)** range + +### cfiFromRange + +Get an EpubCFI from a Dom Range + +**Parameters** + +- `range` **[Range](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input)** +- `ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +Returns **[EpubCFI](#epubcfi)** cfi + +### cfiFromNode + +Get an EpubCFI from a Dom node + +**Parameters** + +- `node` **[node](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling)** +- `ignoreClass` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** + +Returns **[EpubCFI](#epubcfi)** cfi + +### size + +Size the contents to a given width and height + +**Parameters** + +- `width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** +- `height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** + +### columns + +Apply columns to the contents for pagination + +**Parameters** + +- `width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `columnWidth` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `gap` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +### scaler + +Scale contents from center + +**Parameters** + +- `scale` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `offsetX` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `offsetY` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +### fit + +Fit contents into a fixed width and height + +**Parameters** + +- `width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** + +### direction + +Set the direction of the text + +**Parameters** + +- `dir` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** "rtl" | "ltr" (optional, default `"ltr"`) + +### writingMode + +Set the writingMode of the text + +**Parameters** + +- `mode` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** "horizontal-tb" | "vertical-rl" | "vertical-lr" (optional, default `"horizontal-tb"`) + +### listenedEvents + +Get DOM events that are listened for and passed along + +## Mapping + +Map text locations to CFI ranges + +**Parameters** + +- `layout` +- `direction` +- `axis` +- `dev` + +### section + +Find CFI pairs for entire section at once + +**Parameters** + +- `view` + +### page + +Find CFI pairs for a page + +**Parameters** + +- `contents` +- `cfiBase` +- `start` +- `end` + +## Core + +Core Utilities and Helpers + +### requestAnimationFrame + +Vendor prefixed requestAnimationFrame + +Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** requestAnimationFrame + +### uuid + +Generates a UUID +based on: + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** uuid + +### documentHeight + +Gets the height of a document + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** height + +### isElement + +Checks if a node is an element + +**Parameters** + +- `obj` + +Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + +### isNumber + +**Parameters** + +- `n` + +Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + +### isFloat + +**Parameters** + +- `n` + +Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + +### prefixed + +Get a prefixed css property + +**Parameters** + +- `unprefixed` + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +### defaults + +Apply defaults to an object + +**Parameters** + +- `obj` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + +Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + +### extend + +Extend properties of an object + +**Parameters** + +- `target` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + +Returns **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + +### insert + +Fast quicksort insert for sorted array -- based on: + + +**Parameters** + +- `item` **any** +- `array` **[array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** +- `compareFunction` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** location (in array) + +### locationOf + +Finds where something would fit into a sorted array + +**Parameters** + +- `item` **any** +- `array` **[array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** +- `compareFunction` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** +- `_start` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** +- `_end` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** location (in array) + +### indexOfSorted + +Finds index of something in a sorted array +Returns -1 if not found + +**Parameters** + +- `item` **any** +- `array` **[array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** +- `compareFunction` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** +- `_start` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** +- `_end` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** index (in array) or -1 + +### bounds + +Find the bounds of an element +taking padding and margin into account + +**Parameters** + +- `el` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** + +Returns **{width: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), height: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)}** + +### borders + +Find the bounds of an element +taking padding, margin and borders into account + +**Parameters** + +- `el` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** + +Returns **{width: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), height: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)}** + +### windowBounds + +Find the equivelent of getBoundingClientRect of a browser window + +Returns **{width: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), height: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), top: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), left: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), right: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), bottom: [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)}** + +### indexOfTextNode + +Gets the index of a text node in its parent + +**Parameters** + +- `textNode` **[node](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling)** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** index + +### indexOfElementNode + +Gets the index of an element node in its parent + +**Parameters** + +- `elementNode` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** + +Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** index + +### isXml + +Check if extension is xml + +**Parameters** + +- `ext` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + +### createBlob + +Create a new blob + +**Parameters** + +- `content` **any** +- `mime` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)** + +### createBlobUrl + +Create a new blob url + +**Parameters** + +- `content` **any** +- `mime` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** url + +### revokeBlobUrl + +Remove a blob url + +**Parameters** + +- `url` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +### createBase64Url + +Create a new base64 encoded url + +**Parameters** + +- `content` **any** +- `mime` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** url + +### type + +Get type of an object + +**Parameters** + +- `obj` **[object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** type + +### parse + +Parse xml (or html) markup + +**Parameters** + +- `markup` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** +- `mime` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** +- `forceXMLDom` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** force using xmlDom to parse instead of native parser + +Returns **[document](https://developer.mozilla.org/en-US/docs/Web/JavaScript)** document + +### qs + +querySelector polyfill + +**Parameters** + +- `el` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** +- `sel` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** selector string + +Returns **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** element + +### qsa + +querySelectorAll polyfill + +**Parameters** + +- `el` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** +- `sel` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** selector string + +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)>** elements + +### qsp + +querySelector by property + +**Parameters** + +- `el` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** +- `sel` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** selector string +- `props` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<props>** + +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)>** elements + +### sprint + +Sprint through all text nodes in a document + +**Parameters** + +- `root` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** element to start with +- `func` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** function to run on each element + +### walk + +**Parameters** + +- `node` **[node](https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling)** +- `callback` +- `return` **callback** false for continue,true for break inside callback + +### blob2base64 + +Convert a blob to a base64 encoded string + +**Parameters** + +- `blob` **Blog** + +Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +### defer + +Creates a new pending promise and provides methods to resolve or reject it. +From: + +### querySelectorByType + +querySelector with filter by epub type + +**Parameters** + +- `html` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** +- `element` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** element type to find +- `type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** epub type to find + +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)>** elements + +### findChildren + +Find direct decendents of an element + +**Parameters** + +- `el` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** + +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)>** children + +### parents + +Find all parents (ancestors) of an element + +**Parameters** + +- `node` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** + +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)>** parents + +### filterChildren + +Find all direct decendents of a specific type + +**Parameters** + +- `el` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** +- `nodeName` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** +- `single` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** + +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)>** children + +### getParentByTagName + +Filter all parents (ancestors) with tag name + +**Parameters** + +- `node` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** +- `tagname` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + +Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)>** parents + +### RangeObject + +Lightweight Polyfill for DOM Range diff --git a/src/layout.js b/src/layout.js index c84e37d..8b0ebec 100644 --- a/src/layout.js +++ b/src/layout.js @@ -1,3 +1,7 @@ +import { extend } from "./utils/core"; +import { EVENTS } from "./utils/constants"; +import EventEmitter from "event-emitter"; + /** * Figures out the CSS values to apply for a layout * @class @@ -61,7 +65,8 @@ class Layout { } else { this._flow = "paginated"; } - this.props.flow = this._flow; + // this.props.flow = this._flow; + this.update({flow: this._flow}); } return this._flow; } @@ -76,7 +81,8 @@ class Layout { if (spread) { this._spread = (spread === "none") ? false : true; - this.props.spread = this._spread; + // this.props.spread = this._spread; + this.update({spread: this._spread}); } if (min >= 0) { @@ -100,10 +106,11 @@ class Layout { //-- Check the width and create even width columns // var fullWidth = Math.floor(_width); var width = _width; + var height = _height; var section = Math.floor(width / 12); - var colWidth; + var columnWidth; var spreadWidth; var pageWidth; var delta; @@ -125,42 +132,54 @@ class Layout { //-- Double Page if(divisor > 1) { // width = width - gap; - // colWidth = (width - gap) / divisor; + // columnWidth = (width - gap) / divisor; // gap = gap / divisor; - colWidth = (width / divisor) - gap; - pageWidth = colWidth + gap; + columnWidth = (width / divisor) - gap; + pageWidth = columnWidth + gap; } else { - colWidth = width; + columnWidth = width; pageWidth = width; } if (this.name === "pre-paginated" && divisor > 1) { - width = colWidth; + width = columnWidth; } - spreadWidth = (colWidth * divisor) + gap; + spreadWidth = (columnWidth * divisor) + gap; delta = width; this.width = width; - this.height = _height; + this.height = height; this.spreadWidth = spreadWidth; this.pageWidth = pageWidth; this.delta = delta; - this.columnWidth = colWidth; + this.columnWidth = columnWidth; this.gap = gap; this.divisor = divisor; - this.props.width = width; - this.props.height = _height; - this.props.spreadWidth = spreadWidth; - this.props.pageWidth = pageWidth; - this.props.delta = delta; + // this.props.width = width; + // this.props.height = _height; + // this.props.spreadWidth = spreadWidth; + // this.props.pageWidth = pageWidth; + // this.props.delta = delta; + // + // this.props.columnWidth = colWidth; + // this.props.gap = gap; + // this.props.divisor = divisor; + + this.update({ + width, + height, + spreadWidth, + pageWidth, + delta, + columnWidth, + gap, + divisor + }); - this.props.columnWidth = colWidth; - this.props.gap = gap; - this.props.divisor = divisor; } /** @@ -211,6 +230,22 @@ class Layout { }; } + + update(props) { + // Remove props that haven't changed + Object.keys(props).forEach((propName) => { + if (this.props[propName] === props[propName]) { + delete props[propName]; + } + }); + + if(Object.keys(props).length > 0) { + let newProps = extend(this.props, props); + this.emit(EVENTS.LAYOUT.UPDATED, newProps, props); + } + } } +EventEmitter(Layout.prototype); + export default Layout; diff --git a/src/managers/continuous/index.js b/src/managers/continuous/index.js index 22cd303..e8510f0 100644 --- a/src/managers/continuous/index.js +++ b/src/managers/continuous/index.js @@ -33,7 +33,8 @@ class ContinuousViewManager extends DefaultViewManager { flow: this.settings.flow, layout: this.layout, width: 0, - height: 0 + height: 0, + forceEvenPages: false }; this.scrollTop = 0; diff --git a/src/managers/default/index.js b/src/managers/default/index.js index 6edbd00..2dab8dd 100644 --- a/src/managers/default/index.js +++ b/src/managers/default/index.js @@ -34,7 +34,8 @@ class DefaultViewManager { layout: this.layout, method: this.settings.method, // srcdoc, blobUrl, write width: 0, - height: 0 + height: 0, + forceEvenPages: true }; this.rendered = false; @@ -403,8 +404,6 @@ class DefaultViewManager { if(left <= this.container.scrollWidth) { this.scrollBy(this.layout.delta, 0, true); - } else if ((left - this.layout.pageWidth) === this.container.scrollWidth) { - this.scrollTo(this.container.scrollWidth - this.layout.delta, 0, true); } else { next = this.views.last().section.next(); } @@ -486,8 +485,6 @@ class DefaultViewManager { if(left <= this.container.scrollWidth) { this.scrollBy(this.layout.delta, 0, true); - } else if ((left - this.layout.pageWidth) === this.container.scrollWidth) { - this.scrollTo(this.container.scrollWidth - this.layout.delta, 0, true); } else { prev = this.views.first().section.prev(); } diff --git a/src/managers/views/iframe.js b/src/managers/views/iframe.js index 067d25a..effc8e5 100644 --- a/src/managers/views/iframe.js +++ b/src/managers/views/iframe.js @@ -149,7 +149,7 @@ class IframeView { .then(function(){ // apply the layout function to the contents - this.settings.layout.format(this.contents); + this.layout.format(this.contents); // find and report the writingMode axis let writingMode = this.contents.writingMode(); @@ -275,15 +275,16 @@ class IframeView { width = Math.ceil(width / this.layout.pageWidth) * this.layout.pageWidth; } - /* - columns = Math.ceil(width / this.settings.layout.delta); - if ( this.settings.layout.divisor > 1 && - this.settings.layout.name === "reflowable" && - (columns % 2 > 0)) { - // add a blank page - width += this.settings.layout.gap + this.settings.layout.columnWidth; + if (this.settings.forceEvenPages) { + columns = (width / this.layout.delta); + if ( this.layout.divisor > 1 && + this.layout.name === "reflowable" && + (columns % 2 > 0)) { + // add a blank page + width += this.layout.gap + this.layout.columnWidth; + } } - */ + } // Expand Vertically else if(this.settings.axis === "vertical") { height = this.contents.textHeight(); @@ -395,7 +396,7 @@ class IframeView { if(this.displayed && this.iframe) { this.expand(); if (this.contents) { - this.settings.layout.format(this.contents); + this.layout.format(this.contents); } } }); @@ -404,7 +405,7 @@ class IframeView { if(this.displayed && this.iframe) { this.expand(); if (this.contents) { - this.settings.layout.format(this.contents); + this.layout.format(this.contents); } } }); @@ -414,6 +415,11 @@ class IframeView { setLayout(layout) { this.layout = layout; + + if (this.contents) { + this.layout.format(this.contents); + this.expand(); + } } setAxis(axis) { diff --git a/src/rendition.js b/src/rendition.js index 7b372ac..d30f43a 100644 --- a/src/rendition.js +++ b/src/rendition.js @@ -478,6 +478,28 @@ class Rendition { this.manager.moveTo(offset); } + /** + * Trigger a resize of the views + * @param {number} [width] + * @param {number} [height] + */ + resize(width, height){ + if (width) { + this.settings.width = width; + } + if (height) { + this.settings.height = width; + } + this.manager.resize(width, height); + } + + /** + * Clear all rendered views + */ + clear(){ + this.manager.clear(); + } + /** * Go to the next "page" in the rendition * @return {Promise} @@ -578,6 +600,11 @@ class Rendition { this._layout.spread(settings.spread, this.settings.minSpreadWidth); // this.mapping = new Mapping(this._layout.props); + + this._layout.on(EVENTS.LAYOUT.UPDATED, (props, changed) => { + console.log("layout", props); + this.emit(EVENTS.RENDITION.LAYOUT, props); + }) } if (this.manager && this._layout) { diff --git a/src/utils/constants.js b/src/utils/constants.js index 2c53f5c..47adb86 100644 --- a/src/utils/constants.js +++ b/src/utils/constants.js @@ -45,6 +45,10 @@ export const EVENTS = { LOCATION_CHANGED : "locationChanged", RELOCATED : "relocated", MARK_CLICKED : "markClicked", - SELECTED : "selected" + SELECTED : "selected", + LAYOUT: "layout" + }, + LAYOUT : { + UPDATED : "updated" } } diff --git a/src/utils/core.js b/src/utils/core.js index cc1b8e1..749f22d 100644 --- a/src/utils/core.js +++ b/src/utils/core.js @@ -113,7 +113,7 @@ export function defaults(obj) { } /** - * Extend undefined properties of an object + * Extend properties of an object * @param {object} target * @returns {object} * @memberof Core