Bookhoard/foliate-js
1
0
Fork 0
mirror of https://github.com/john-okeefe/foliate-js.git synced 2026-09-09 11:29:14 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
John Factotum
2022-10-22 14:17:14 +00:00
committed by GitHub
parent 5103dc9b90
commit c3598e3c38
1 changed files with 25 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+25 -1
View File
@@ -27,7 +27,13 @@ Among other things, the fixed-layout renderer is notably unfinished at the momen
### Overview
The project is designed to be modular. It has two renderers, one for paginating reflowable books, and one for fixed layout. The `View` class defined in `view.js` is the one that strings everything together.
This project uses native ES modules. There's no build step, and you can import them directly.
The modules are designed to be modular. In general, they don't directly depend on each other (except for `epub.js`, which imports `epubcfi.js`). Instead they depend on certain interfaces, detailed below.
The exception is `view.js`. It is the one that strings everything together, and you can think of it as the main entry point of the library.
### The Main Interface for Books
Processors for each book format return an object that implements the following interface:
- `.sections`: an array of sections in the book. Each item has the following properties:
@@ -77,6 +83,18 @@ Note that KF8 files can contain fonts that are zlib-compressed. They need to be
### The Renderers
It has two renderers, one for paginating reflowable books, and one for fixed-layout. The constructor of a renderer takes a single object with the following properties:
- `.book`: the book object that will be rendered.
- `.onLoad(doc, index)`: callback when a section is loaded. Takes a `Document` object and the index of the section.
- `.onRelocated(range, index, fraction)`: callback when locations changes. `range` is a `Range` object containing the current visible area. `fraction` is a number between 0 and 1, representing the reading progress within the section.
- `createOverlayers(doc, index)`: callback for adding overlays to the page. It should return an object whose property values are overlayer objects (see the description for `overlayer.js` below). The key names can be any string you want.
A renderer's interface is currently mainly:
- `.element`: the DOM element of the renderer. It needs to be manually appended to the document by the consumer of the renderer.
- `.goTo({ index, anchor })`: navigate to a destination. The argument has the same type as the one returned by `.resolveHref()` in the book object.
- `.prev()`: go to previous page.
- `.next()`: go to next page.
The paginator uses the same pagination strategy as [Epub.js](https://github.com/futurepress/epub.js): it uses CSS multi-column. As such it shares much of the same limitations (it's slow, some CSS styles do not work as expected, and other bugs). There are a few differences:
- It is a totally standalone module. You can use it to paginate any content.
- It is much simpler, but currently there's no support for continuous scrolling.
@@ -141,6 +159,12 @@ It can parse and stringify spatial and temporal offsets, as well as text locatio
There is a generic module for overlaying arbitrary SVG elements, `overlayer.js`. It can be used to implement highlighting text for annotations. It's the same technique used by [marks-pane](https://github.com/fchasen/marks), used by Epub.js, but it's designed to be easily extensible. You can return any SVG element in the `draw` function, making it possible to add custom styles such as squiggly lines or even free hand drawings.
The overlay has no event listeners by default. It only provides a `.hitTest(event)` method, that can be used to do hit tests. Currently it does this with the client rects of `Range`s, not the element returned by `draw()`.
An overlayer object implements the following interface for the consumption of renderers:
- `.element`: the DOM element of the overlayer. This element will be inserted, resized, and positioned automatically by the renderer on top of the page.
- `.redraw()`: called by the renderer when the overlay needs to be redrawn.
### Searching
It provides a search module, which can in fact be used as a standalone module for searching across any array of strings. There's no limit on the number of strings a match is allowed to span. It's based on `Intl.Collator` and `Intl.Segmenter`, to support ignoring diacritics and matching whole words only. It's extrenely slow, and you'd probably want to load results incrementally.