reader.locateResource()
Map CFIs and spine items to page indexes, DOM nodes and ranges with reader.locateResource(): its parameters, its shallow and load modes, and the live result.
Locate a given resource and give you extra information such as absolute page index, relevant nodes, offset etc. This is most useful when you want to locate resources such as CFI.
This method is live. Each time the reader publishes pages, and each time a loaded spine item starts to unload, it locates the resources again once the browser is idle, and emits. A resource whose published pages and item's document did not change since it was last located is not located again, and emits nothing. The values follow the published pages, see Page indexes.
const consolidatedResource$ = reader.locateResource(resource, options)Reference
Section titled “Reference”locateResource(resource, options)
type CfiLocatableResource = { cfi: string}
type ProseParsedCfi = { // This will always be set and is statically inferred from the CFI format. // This does not mean the range is valid. isCfiRange: boolean itemIndex: number}
export type LocatableResource = SpineItem | CfiLocatableResource
export type ConsolidatedResource = CfiLocatableResource & ProseParsedCfi & { // The page of its spine item the resource is on, once it is known. itemPageIndex?: number // The page of the book the resource is on, as the published pages give it: // known with itemPageIndex once pages are published. absolutePageIndex?: number // The node the CFI points to, while its item is loaded. node: Node | null // The character offset at the end of the CFI, as written. offset?: number // The offset the CFI resolves to, while its item is loaded. startOffset?: number // This is the resolved range if there is one and if it's resolvable. // Meaning, a valid range for this book item range?: Range | null}
locateResource(resource, options)Parameters
Section titled “Parameters”resource: An object or array of objects that extendsLocatableResource. Resources at the same cfi share one consolidation, and each comes back with its ownresource. A spine item is located at the cfi of its start. An array emits once each time its resources are located again, not once for each resource. When you locate a new array synchronously after you unsubscribe from the previous one, asswitchMapdoes when the array changes, a CFI that both arrays hold keeps its values and is not located again.options?:mode?:"shallow" | "load" : Defaultload. Shallow means that the item will not be loaded if needed. Load keeps a reflowable item loaded while you are subscribed, throughkeepSpineItemLoaded(), and releases its hold a second after you unsubscribe. Neither mode loads a pre-paginated item: its page indexes need no document, and itsnode,startOffsetandrangeresolve only while it is loaded for another reason, such as being around the reading position. By using shallow you avoid loading documents excessively but you will only get the values as precise as possible with the current reader state.
Page indexes
Section titled “Page indexes”itemPageIndex and absolutePageIndex are given only when the reader knows them:
- A spine item, a CFI that names only its item, and a CFI of a pre-paginated item are on the first page of their item. Their
itemPageIndexis known at once, loaded or not, and theirabsolutePageIndexonce pages are published. - Any other CFI of a reflowable item is on the page of the node it points to. Its page is known when it is located while its item is loaded and laid out, the published pages describe the item as its latest layout lays it out, and the CFI resolves in it. It keeps that page while a layout that can change the item is pending, until the next pages are published. It is
undefinedotherwise.
In the shallow mode, a CFI of a reflowable item that is not loaded therefore has no page. It gets one when its item loads, for example because the reader goes there, and loses it as soon as its item unloads. In the load mode, it has no page until its item has loaded.
The values follow the pages the reader publishes, which reader.spine.layout$ emits. absolutePageIndex is the page they give, so it is known once pages are published. From the moment a layout that can change the item is requested, after a resize or a change of font size for example, until its pages are published, reader.spine.isLayoutCurrentFor() is false for the item. In that time, a resource located on the published pages keeps its values. A CFI of the second kind above that is located in that time has no page until the next pages are published, and neither has one last located on pages published before the current ones. Every resource is located again once the next pages are published.
Returns
Section titled “Returns”Observable<{ resource: T; meta: ConsolidatedResource }>Or if you passed an array of resources
Observable<{ resource: T; meta: ConsolidatedResource }[]>An observable containing the initial resources and their consolidated metadata. It completes when the reader is destroyed.