Basic navigation

Introduction

This tutorial will teach you how to set up basic navigation using the next and previous methods. It will also show you how to use the Colibrio EngineEvents to see when such navigation is possible.

Audience

Developer who knows Typescript and some basic HTML and CSS.

Prerequisites

This tutorial builds upon the app that was created in the hello world tutorial.

Not included in this tutorial

Other ways of navigation, such as navigating to specific locations in a publication using Locators.

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

Creating the AppNavigation class

Create a new file in the /src directory called AppNavigation.ts and in that file, create a new class called AppNavigation.

In the constructor, set up the click listeners on the buttons, call the methods to update the buttons' disabled state and set up the EngineEvent listeners to let the reading system tell you when navigation to the next and previous spread is possible.

export class AppNavigation {
    private previousButton: HTMLButtonElement;
    private nextButton: HTMLButtonElement;

    constructor(private readerView: IReaderView, container: HTMLElement) {
        const previousButton = container.querySelector<HTMLButtonElement>('#previous-button');
        const nextButton = container.querySelector<HTMLButtonElement>('#next-button');
        if (!previousButton || !nextButton) {
            throw new Error('Unable to find #previous-button or #next-button');
        }
        this.previousButton = previousButton;
        this.nextButton = nextButton;
        this.previousButton.addEventListener('click', this.onPreviousButtonClicked);
        this.nextButton.addEventListener('click', this.onNextButtonClicked);
        this.updatePreviousButtonDisabledState();
        this.updateNextButtonDisabledState();
        this.setupColibrioEventListeners();
    }

    // You will add the rest of the methods here...
}

Colibrio EngineEvents

The Colibrio Reading System will emit events to let you know about things happening inside the reading system. You will use two of those events in this tutorial, but there are many more that you can read about by looking up IEngineEventTypeMap in the API documentation.

The events canPerformPreviousChanged and canPerformNextChanged tell you when the reading system is ready for navigation using the ReaderView.previous() and ReaderView.next() methods.

private setupColibrioEventListeners(): void {
    this.readerView.addEngineEventListener('canPerformNextChanged', this.updateNextButtonDisabledState);
    this.readerView.addEngineEventListener('canPerformPreviousChanged', this.updatePreviousButtonDisabledState);
}

You can use these events to update the disabled state of the navigation buttons.

private updateNextButtonDisabledState = () => {
    const canPerformNext = this.readerView.canPerformNext();
    if (canPerformNext) {
        this.nextButton.removeAttribute('disabled');
    } else {
        this.nextButton.setAttribute('disabled', '');
    }
}

private updatePreviousButtonDisabledState = () => {
    const canPerformPrevious = this.readerView.canPerformPrevious();
    if (canPerformPrevious) {
        this.previousButton.removeAttribute('disabled');
    } else {
        this.previousButton.setAttribute('disabled', '');
    }
}

Navigation

Navigating to the previous or next page in a publication is just one method call on a ReaderView. The methods return Promises that resolve if the navigation was successful and reject if there was an error navigating.

private navigateNext = () => {
    this.readerView.next().catch(err => {
        Logger.logError(err);
    });
}

private navigatePrevious = () => {
    this.readerView.previous().catch(err => {
        Logger.logError(err);
    });
};

Integrating with the App

HTML and CSS

In index.html, add a new container <div> with two buttons, one for the previous navigation and one for next. Add it after the readingsystem-viewport div so the buttons appear under the reader.

<div id="navigation-container">
    <button id="previous-button">Previous</button>
    <button id="next-button">Next</button>
</div>

Also add some CSS for the new <div> to make the container as wide as the reader and add some nice spacing to the buttons.

#navigation-container {
    width: 1000px;
    padding-top: 20px;
    display: flex;
    justify-content: space-around;
}

Typescript

In the App.ts file, add a new instance variable to hold the AppNavigation and create a new method called createAppNavigation.

class App {
    private appNavigation: AppNavigation | undefined;
    //...
}

createAppNavigation(navigationContainer: HTMLElement): void {
    if (this.appNavigation) {
        Logger.logError('AppNavigation component already created.');
    } else {
        this.appNavigation = new AppNavigation(this.readerView, navigationContainer);
    }
}

In index.ts, after you create a new App, call the createAppNavigationmethod and the AppNavigation will be ready to be used.

const app = new App(viewElement, apiKey);

const navigationContainer = document.getElementById('navigation-container');
if (navigationContainer) {
    app.createAppNavigation(navigationContainer);
} else {
    Logger.logError('Unable to find #navigation-container');
}

That’s it. You should now have an app set up with navigation to the next and previous page with buttons that are enabled or disabled based on the navigation possibilities.

Concepts

EngineEvent

Engine events are generated by the Colibrio Reading System whenever something happens that you, as a developer, might want to know about. It could be something like a pointer event, an event telling you that new content has been rendered, or many other things. For a full list of all possible events, please refer to the API documentation.

ReaderView

Handles rendering and navigation.