Annotations enhancer
Install @prose-reader/enhancer-annotations, create annotations with createAnnotation and give each one an id of your own before you store it, show them as highlights, find the annotations of each page with annotationsByItemPage$, find the pages that can hold one with candidates$, and avoid the root CFI you get on a blank page.
Getting Started
Section titled “Getting Started”npm install @prose-reader/enhancer-annotations @prose-reader/core @prose-reader/shared rxjsAll three are peer dependencies: the enhancer runs against the reader your app creates, so it shares that reader's copies rather than bringing its own.
Creating an annotation
Section titled “Creating an annotation”reader.annotations.createAnnotation() gives a new annotation its cfi and, for a selection, its highlightedText. Pass it one of two things:
- a selection and the index of its spine item, as
reader.selection.getSelection()gives them, for a highlight; - the absolute index of a page, for a bookmark.
const currentSelection = reader.selection.getSelection()
if (currentSelection) { const highlight = reader.annotations.createAnnotation({ itemIndex: currentSelection.itemIndex, selection: currentSelection.selection, })
if (highlight) { saveAnnotation({ ...highlight, id: crypto.randomUUID(), highlightColor: "yellow", notes: "", }) }}
const bookmark = reader.annotations.createAnnotation({ absolutePageIndex })It returns { cfi, highlightedText } for a selection and { cfi } for a page: strings and nothing else. Add an id of your own and the other fields of your annotation to it, such as highlightColor and notes, and store the result as it is: in IndexedDB, for example. The type of an annotation without its id is NewAnnotation.
- For a selection, the CFI is the range of the selection, and
highlightedTextis the text of that range: see The text of a highlight. - For a page, the CFI points to the first visible node of the page, or to the root of its spine item when the page has none: see Blank pages and annotations. The result has no
highlightedText. - It returns
undefinedwhen the reader has no such spine item or page, or when the selection holds no range.
The reader only needs each id to be unique among the annotations you give it, so your ids can take the form your store uses.
Do not store a page index with an annotation: its page changes with the layout and the device. See Danger of persisting weak references.
The text of a highlight
Section titled “The text of a highlight”highlightedText is the text of the range, as Range.toString() gives it: the text nodes of the document, joined.
- It keeps the whitespace that the document holds, such as the line breaks and tabs of its source.
- It adds nothing between two paragraphs.
- It does not depend on CSS, the layout or the browser, so it is the same on every device.
It is not the text of the selection as the browser renders it, which Selection.toString() gives and which differs between browsers.
Store it to list, export or search highlights without the book. To find out whether the passage at a stored CFI still holds that text, read the passage the same way: range.toString() of the range that the CFI resolves to, such as the range that reader.locateResource() gives. To show it outside of HTML, collapse its whitespace, as HTML does when it renders text.
Showing highlights
Section titled “Showing highlights”Give the enhancer your annotations as an observable. Each time they change, emit a new array, and put each changed annotation in it as a new object:
import { createReader } from "@prose-reader/core"import { type Annotation, annotationsEnhancer,} from "@prose-reader/enhancer-annotations"import { BehaviorSubject } from "rxjs"
const annotations$ = new BehaviorSubject<Annotation[]>([])
const reader = annotationsEnhancer(createReader)({ manifest, annotations: { annotations$ },})
// The user changed the color of an annotation.annotations$.next( annotations$.value.map((annotation) => annotation.id === changedId ? { ...annotation, highlightColor: "red" } : annotation, ),)
// The user removed an annotation.annotations$.next( annotations$.value.filter((annotation) => annotation.id !== removedId),)The enhancer compares each entry with the previous one by reference. It ignores an array that holds the same objects as the previous one, so it does not draw again an annotation that you change in place.
The enhancer draws a highlight for each annotation whose CFI is a range, while
the document of its spine item is loaded. The highlight covers each line of the
text that the range covers, from the line's first selected character to its
last. It covers the box of each img, svg, math, video, audio,
canvas, iframe, object or embed element that the range covers whole,
even one that holds text. It does not cover the blank space beside a line. It
is drawn:
- in its
highlightColor, or yellow when it has none, with a note icon when it hasnotes; - with a red dashed border when it is the first annotation in the array whose
selectedistrue.
The enhancer matches each highlight to its annotation by id, so give each
annotation an id of its own. When an annotation changes, the enhancer draws
its highlight again. When an annotation leaves the array, the enhancer removes
its highlight at once.
reader.annotations.highlightTap$ emits { event, annotation } for each tap on
a highlight. annotation is the annotation of the tapped highlight. Where
highlights overlap, a tap reaches the highlight drawn on top, and the stream
reports that one. It completes when the reader is destroyed.
Finding the annotations of a page
Section titled “Finding the annotations of a page”reader.annotations.annotationsByItemPage$ emits the annotations whose page is
known, by spine item index, then by page index in the item, in the order of the
array. A range is on the page where it starts. Read it for anything shown per
page, such as a mark on each annotated page:
reader.annotations.annotationsByItemPage$.subscribe((annotationsByItemPage) => { const annotationsOfPage = annotationsByItemPage.get(itemIndex)?.get(pageIndex) ?? []})It locates the annotations with
reader.locateResource() in its shallow
mode, so it loads no chapter, and an annotation has a page as the
Page indexes rules give it.
Unless its CFI names only its chapter, an annotation in a reflowable chapter
that is not loaded has none, and neither has one added while a layout of its
chapter is pending, until that layout's pages are published.
It emits once the annotations are located, then each time an annotation of a page moves to another page, comes, goes or changes. It completes when the reader is destroyed.
The enhancer does not tell bookmarks from highlights: what each kind of annotation means is up to your app. React Reader, for example, takes the annotations of a page whose CFI is not a range as the bookmarks of that page.
Blank pages and annotations
Section titled “Blank pages and annotations”Sometimes you may end up with blank pages. Some of the scenarios that lead to a blank page are:
- Document configured to show a blank page before or after a specific page (by design)
- Document spreading on more than one page but the DOM does not cover all pages
This situation is unfortunate but sometimes by design as well. Trying to annotate a page on which it's impossible to create a CFI from (other than a root CFI) will make it impossible to derive the correct page for it later.
We provide a .candidates$ observable which you can observe to know which page is a good candidate for annotation or not. A good candidate is defined as such:
- Page from a pre-paginated document (there can be only one page anyway)
- Page with a visible DOM node (meaning you can target it with a CFI)
pre-paginated documents are by design always on one page so we don't check whether they have a visible node.
candidates$ emits one boolean per page the reader has published, by absolute page index, each time the reader publishes its pages. Until the reader has published its first pages, it emits an empty array. It gives its latest value to a new subscriber at once, so it can be read with withLatestFrom.
Troubleshoots
Section titled “Troubleshoots”Annotation CFI is empty (root CFI)
Section titled “Annotation CFI is empty (root CFI)”If you get a root CFI when trying to annotate a page, it is likely because we were unable to find a node to create a CFI from. This can happen when trying to annotate a blank page. Try to filter out such pages.