Reading progress slider
Introduction
Objective
Create a slider to keep track of the current reading progress and to navigate in the publication by clicking the slider.
Audience
Typescript developers.
Prerequisites
Based on the code from Adding PDF support
Full code example
For reference, you can find the full code example in the Web framework tutorial repository.
In order to set up the developer environment including where to put your credentials, please follow the steps described in Set up tutorial environment.
Tutorial
The code in this tutorial builds upon the code from the Adding PDF support tutorial.
HTML and CSS
The only thing to do in index.html is to add the element that will be used as a progress slider. It starts out disabled since there is no publication loaded and therefore no timeline yet.
<input id="progress-slider" type="range" min="0" value="0" disabled>Then also update the styles in index.css to make the slider as wide as the reader.
#progress-slider {
width: 90vw;
}AppProgressSlider.ts
The AppProgressSlider class is where you will write most of the code for this tutorial. It’s responsible for rendering a progress slider, navigating the ReaderView using the slider and synchronizing the slider to the publication content that is visible in the ReaderView.
In the constructor, set up the event listeners that will be used to synchronize the slider element with the ReaderView:
A regular
changeevent listener on the slider element that will be used to trigger navigations when a user clicks the slider.A
visibleRangeChangedEngineEventListener that tells you when the visible range in the ReaderView has changed so you can update the slider’s value.
export class AppProgressSlider {
constructor(private readerView: IReaderView, private sliderElement: HTMLInputElement) {
this.sliderElement.addEventListener('change', this.onSliderChange);
this.readerView.addEngineEventListener('visibleRangeChanged', this.onVisibleRangeChanged);
}
/**
* Navigates the ReaderView to the position that most closely matches the new slider value.
*/
private onSliderChange = (): void => {
}
/**
* Updates the slider value based on the visible range in the ReaderView.
*/
private updateSliderValue = (): void => {
}
}Choosing a ContentPositionTimelineUnit
Creating a timeline is a little bit different depending on the type of the publication.
A PDF is always divided into pages so ContentPositionTimelineUnit.PAGES is always available for PDF.
An EPUB can have several available timeline units. For pre-paginated EPUBs it is recommended to use ContentPositionTimelineUnit.PAGES. If the EPUB is reflowable, then ContentPositionTimelineUnit.PAGES will not be available since the number of pages depends on the device and settings used. In this case ContentPositionTimelineUnit.CHARACTERS gives the best result for a progress slider. Use the method readerPublication.getAvailableContentPositionTimelineUnits() to see if ContentPositionTimelineUnit.PAGES is available for the EPUB publication.
private static getTimelineUnitForEpub(readerPublication: IEpubReaderPublication): ContentPositionTimelineUnit {
let availableUnits = readerPublication.getAvailableContentPositionTimelineUnits();
if (availableUnits.includes(ContentPositionTimelineUnit.PAGES)) {
// The PAGES unit is available if the EPUB is pre-paginated. For such publications, it makes the most
// sense to use the PAGES unit, as the timeline will exactly correspond with the pages in the
// publication.
return ContentPositionTimelineUnit.PAGES;
} else {
// For a reflowable publication the number of pages will change depending on how the publication is
// rendered, so to get a consistent timeline your best option is to use the CHARACTERS unit.
return ContentPositionTimelineUnit.CHARACTERS;
}
}Creating the ContentPositionTimeline
Whenever a new publication has been loaded, you need to create a new ContentPositionTimeline. So whenever your app starts loading a new publication, you can call this method with null to disable the old timeline, and then when the publication has finished loading, you call this method with the new ReaderPublication instance to start creating the new timeline.
First we need to know if the publication is an EPUB or PDF publication to determine the ContentPositionTimelineUnit to use.
private static isEpubReaderPublication(readerPublication: IReaderPublication | null): readerPublication is IEpubReaderPublication {
if (!readerPublication) {
return false;
}
return readerPublication.getSourcePublication().getType() === PublicationType.EPUB;
}
private static isPdfReaderPublication(readerPublication: IReaderPublication | null): readerPublication is IPdfReaderPublication {
if (!readerPublication) {
return false;
}
return readerPublication.getSourcePublication().getType() === PublicationType.PDF;
}Creating a timeline is asynchronous, so it's possible that this method is called again before the previous timeline has finished creating. Add an instance variable latestSetReaderPublicationId to keep a running count of when this method is called, to know which timeline is the latest, so you can discard any outdated timeline.
Once the timeline has been created, set the max value of the slider and enable it.
private latestSetReaderPublicationId: number = 0;
private timeline: IContentPositionTimeline | null = null;
...
setReaderPublication(readerPublication: IReaderPublication | null): void {
this.setSliderEnabled(false);
this.timeline = null;
// Creating a timeline is asynchronous, so it's possible that this method is called again before the previous
// timeline has finished creating. Keep a running count of when this method is called, to know which timeline is
// the latest, so you can discard any outdated timeline.
this.latestSetReaderPublicationId++;
const setReaderPublicationCounter = this.latestSetReaderPublicationId;
let timelinePromise: Promise<IContentPositionTimeline>;
if (AppProgressSlider.isEpubReaderPublication(readerPublication)) {
// It's an EPUB publication which may support several kind of units.
const timelineUnit = AppProgressSlider.getTimelineUnitForEpub(readerPublication);
timelinePromise = readerPublication.createContentPositionTimeline(readerPublication.getSpine(), {
unit: timelineUnit,
});
} else if (AppProgressSlider.isPdfReaderPublication(readerPublication)) {
// It's a PDF publication, and PDFs are always pre-paginated, so the PAGES unit is ideal.
timelinePromise = readerPublication.createContentPositionTimeline(readerPublication.getSpine(), {
unit: ContentPositionTimelineUnit.PAGES
});
} else {
// You can only create ContentPositionTimelines for PDFs and EPUBs
return;
}
timelinePromise.then((timeline) => {
if (setReaderPublicationCounter !== this.latestSetReaderPublicationId) {
// The setReaderPublication method has been called again while the timeline was being created, and since
// the timeline is tied to a publication, it is no longer valid.
return;
}
this.timeline = timeline;
// The reason for -1 is so that the slider will be at 100% when you've navigated to the last page.
this.sliderElement.setAttribute('max', '' + (timeline.getLength() - 1));
this.setSliderEnabled(true);
// Set the initial slider value
this.updateSliderValue();
});
}Implementing the onSliderChange function
onSliderChange is the function that's called when a user clicks the slider and the value changes. Use the ContentPositionTimeline instance to convert the slider value to a ContentLocation and then use the ReaderView to navigate to that ContentLocation. Add some error handling and just to be extra safe, since fetching the ContentLocation is an async operation, add a little check to make sure that the timeline is still valid after fetching the ContentLocation.
private onSliderChange = (): void => {
const sliderValue = parseInt(this.sliderElement.value);
if (this.timeline) {
const timeline = this.timeline;
timeline.fetchContentLocation(sliderValue).then(contentLocation => {
if (timeline === this.timeline) {
return this.readerView.goTo(contentLocation)
}
}).catch(err => {
if (!ColibrioError.isColibrioAbortedError(err)) {
// readerView.goTo() is rejected with an ABORTED error, if we get a new `readerView.goTo()` before the
// previous `readerView.goTo()` finished.
// Avoid logging that ABORTED error.
Logger.logError(err);
}
});
}
}Implementing the updateSliderValue function
When the visible range has changed, use the ContentPositionTimeline to convert the visible range to a timeline range and update the slider accordingly. To prevent unnecessary movement of the slider, you can check if the old value is still inside the new visible range. If it is not, set the value to the end of the new visible range minus 1. The reason to take minus 1 is that the end value is the same as the next spread’s start value. If you don’t take minus 1, the slider will only update every other page turn. The reason to use the end value at all is that when the user is on the last spread, the slider will be at 100%.
private updateSliderValue = (): void => {
const visibleRange = this.readerView.getVisibleRange();
if (this.timeline && visibleRange) {
this.timeline.fetchTimelineRange(visibleRange).then((visibleTimelineRange) => {
const oldSliderValue = parseInt(this.sliderElement.value);
// To prevent the slider from jumping after navigating, only change the slider if its old value is
// outside the new visible range.
if (oldSliderValue < visibleTimelineRange.start || oldSliderValue >= visibleTimelineRange.end) {
this.sliderElement.value = '' + (visibleTimelineRange.end - 1);
}
});
}
};setSliderEnabled
Just a little helpful method to add or remove the disabled attribute on the slider element.
private setSliderEnabled(enabled: boolean): void {
const isSliderDisabled = this.sliderElement.getAttribute('disabled') !== null;
if (enabled && isSliderDisabled) {
this.sliderElement.removeAttribute('disabled');
} else if (!enabled && !isSliderDisabled) {
this.sliderElement.setAttribute('disabled', '');
}
}App.ts
Now to use the AppProgressSlider that you’ve just created, you will also need to make some changes to App.ts.
You need to add a new instance variable with the AppProgressSlider, so you can call the appropriate methods when loading or unloading a publication. Also, add a method to create the AppProgressSlider in the first place.
class App {
private appProgressSlider: AppProgressSlider | undefined = undefined;
// ...
createProgressSlider(progressSliderElement: HTMLInputElement) {
this.appProgressSlider = new AppProgressSlider(this.readerView, progressSliderElement);
if (this.readerPublication) {
this.appProgressSlider.setReaderPublication(this.readerPublication);
}
}
}loadAndSetReaderPublication
When unloading a publication, call this.appProgressSlider.setReaderPublication(null) to let the AppProgressSlider know that the old publication is no longer relevant and that the timeline should be disabled. After the new publication is loaded, call setReaderPublication() again, but with the newly loaded publication. Doing this will trigger the creation of a new ContentPositionTimeline.
private async loadAndSetReaderPublication(publication: IPublication | null): Promise<void> {
if (publication) {
const licenseOptions = {
userToken: await SimpleObfuscation.obfuscate(this.userId),
publicationToken: await SimpleObfuscation.obfuscate(publication.getHashSignature())
};
if (this.readerPublication) {
this.readerView.setReaderDocuments([]);
this.appProgressSlider?.setReaderPublication(null)
await this.readingSystemEngine.unloadPublication(this.readerPublication);
}
this.readerPublication = await this.readingSystemEngine.loadPublication(publication, undefined, licenseOptions);
this.readerView.setReaderDocuments(this.readerPublication.getSpine());
this.appProgressSlider?.setReaderPublication(this.readerPublication);
} else {
return Promise.reject('No publication found in the provided file.');
}
}Index.ts
In index.ts you need to find the element that will contain the new progress slider, and also call the method on the App instance to create the AppProgressSlider.
window.onload = () => {
// ...
const progressSliderElement = document.querySelector<HTMLInputElement>('#progress-slider');
if (viewElement) {
const app = new App(viewElement, apiKey, loggedInUserId);
// ...
if (progressSliderElement) {
app.createProgressSlider(progressSliderElement);
} else {
Logger.logError('Unable to find #progress-slider-container');
}
// ...
}
}Concepts
ContentLocation
A ContentLocation describes a position or a range of content in a publication. It also has some utility methods to for example compare the ContentLocation’s position to another ContentLocation.
ContentPositionTimeline
A ContentPositionTimeline is used for describing positions within ReaderPublication content as integers. The unit of measurement can for example be characters, words, pages, or documents.
EngineEvents
The Colibrio Reading System emits events whenever something happens inside the reading system that might be of interest to you as a developer. For a full list of events, please refer to IEngineEventTypeMap in the API documentation.
ReaderView
The ReaderView’s main responsibilities are rendering publication content and navigating in the publication.
ReaderPublication
A publication that has been processed to be used by the Colibrio Reading System. A ReaderPublication wraps a source publication and provides functionality for creating renderable content, full text search and more.
Visible Range
The visible range is a range of content in the form of a ContentLocation that describes what’s currently visible in a ReaderView.