Switching renderers

Introduction

The choice of Renderer has an impact on how publication content is displayed on the screen. This tutorial will teach you how you can switch between the different renderers in the Colibrio reading system. There are renderers that show a single page at a time, renderers that show a spread of two pages and a scrolling renderer.

Objective

Learn how to set up multiple renderers and switching between them, including an introduction to automatically switching renderers using ResponsiveViewRules.

Audience

A developer who knows Typescript and a little bit of HTML and CSS.

Prerequisites

• Set up tutorial environment

• Based on the code from Basic navigation

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

index.html

Add a new <div> to index.html, with a radio button for each renderer (and one for setting ReaderView.setResponsiveRendererSelectionEnabled()). These radio buttons will be used to switch between the different renderers or to enable responsive renderer selection.

<div id="renderer-switcher">
    <p>Try resizing the window with "Responsive" selected to see how the responsive view
        rules affect the renderer choice.</p>
    <p>Active renderer: <span id="renderer-active-name"></span></p>
    <label>
        Responsive
        <input type="radio" name="renderer-select" value="Responsive" checked>
    </label>
    <label>
        Stack
        <input type="radio" name="renderer-select" value="Stack">
    </label>
    <label>
        FlipBook
        <input type="radio" name="renderer-select" value="FlipBook">
    </label>
    <label>
        SinglePageSwipe
        <input type="radio" name="renderer-select" value="SinglePageSwipe">
    </label>
    <label>
        SpreadSwipe
        <input type="radio" name="renderer-select" value="SpreadSwipe">
    </label>
    <label>
        SingleDocumentScroll
        <input type="radio" name="renderer-select" value="SingleDocumentScroll">
    </label>
</div>

AppRendererSwitcher.ts

The AppRendererSwitcher class is responsible for adding all the different renderers to the ReaderView and for the UI related to switching between the renderers.

Create a new file called AppRendererSwitcher.ts and in that file, create a class with the same name. Go ahead and declare all the properties and create placeholders for all the methods that will be implemented in this tutorial.

export class AppRendererSwitcher {
    constructor(private readerVIew: IReaderView, private containerElem: HTMLElement) {
    }
    private activateRenderer(rendererName: AppRendererName): void {
    }
    private setupRadioButtons(): void {
    }
    private setupActiveRendererNameElement(): HTMLParagraphElement {
    }
}

Renderer Names

In the global scope in AppRendererSwitcher.ts, define an enum with the names to use for the renderers. In this code example, it is important that these names are the same as the values for the radio buttons defined in index.html, but in general you can use whatever name you want.

The names can be used to identify the renderer and to get the renderer from the ReaderView. Responsive is not a name for a specific renderer, but will be used to enable responsive renderer selection, which allows the ReaderView to automatically select a renderer based on the rules that were provided when adding the renderers and which renderer best fits the viewport.

enum RendererName {
    RESPONSIVE = 'Responsive',
    STACK = 'Stack',
    FLIP_BOOK = 'FlipBook',
    SINGLE_PAGE_SWIPE = 'SinglePageSwipe',
    SPREAD_SWIPE = 'SpreadSwipe',
    SINGLE_DOCUMENT_SCROLL = 'SingleDocumentScroll'
}

constructor

In the constructor, start by creating new instances of all the renderers. Note the options parameter, setting a name for each renderer. The names will be used when setting up the radio buttons to switch renderers, as well as to display which renderer is currently active. For other renderer options, take a look at the API documentation for each renderer.

constructor(private readerView: IReaderView, private containerElem: HTMLElement) {
        const stackRenderer = new StackRenderer({name: RendererName.STACK});
        const flipBookRenderer = new FlipBookRenderer({name: RendererName.FLIP_BOOK});
        const singlePageSwipeRenderer = new SinglePageSwipeRenderer({name: RendererName.SINGLE_PAGE_SWIPE});
        const spreadSwipeRenderer = new SpreadSwipeRenderer({name: RendererName.SPREAD_SWIPE});
        const scrollRenderer = new SingleDocumentScrollRenderer({name: RendererName.SINGLE_DOCUMENT_SCROLL});
    // ... 
}

After creating the renderers, you also need to add them to the ReaderView before they can be used. For the Stack and the FlipBook renderers, also add a responsive view rule. These rules define when the ReaderView should use these renderers when responsive renderer selection is enabled. It is enabled by default, but will be disabled if you call ReaderView.setActiveRenderer(). To enable it again, call ReaderView.setResponsiveRendererSelection(true).

this.readerView.addRenderer(stackRenderer, "(orientation: portrait)");
this.readerView.addRenderer(flipBookRenderer, "(orientation: landscape)");

For the remaining renderers, just pass a function that always returns false as the ResponsiveViewRule. This means that they will not be automatically picked by the ReaderView, but will still be available if you explicitly call ReaderView.setActiveRenderer().

this.readerView.addRenderer(singlePageSwipeRenderer, () => false);
this.readerView.addRenderer(spreadSwipeRenderer, () => false);
this.readerView.addRenderer(scrollRenderer, () => false);

Then call the method to set up the element that will be used to display the currently active renderer.

this.setupActiveRendererNameElement();

Finally, call the method to set up the radio buttons that will be used to switch between the different renderers.

this.setupRadioButtons();

That’s all for the constructor. Now on to the other methods!

setupActiveRendererNameElement

A method to update the UI whenever the ReaderView’s active renderer has changed. Add an engine event listerer, listening to the activeRendererChanged event and then get the new renderer using ReaderView.getActiveRenderer(). For a list of all engine events, take a look at IEngineEventTypeMap in the API documentation.

private setupActiveRendererNameElement() {
    const activeRendererNameElement = this.containerElem.querySelector<HTMLSpanElement>('#renderer-active-name');

    if (activeRendererNameElement) {
        activeRendererNameElement.innerText = this.readerView.getActiveRenderer()?.getName() ?? 'none';

        this.readerView.addEngineEventListener('activeRendererChanged', () => {
            activeRendererNameElement.innerText = this.readerView.getActiveRenderer()?.getName() ?? 'none';
        });
    } else {
        Logger.logError('Unable to find element with id #renderer-active-name');
    }
}

setupRadioButtons

In the setupRadioButtons method, set up the event listeners for switching renderers when a radio button has been selected.

private setupRadioButtons(): void {
    for (let rendererName of Object.values(RendererName)) {
        const valueSelector = "[value=" + rendererName + "]";
        const radioButton = this.containerElem.querySelector<HTMLInputElement>(valueSelector);
        if (radioButton) {
            radioButton.addEventListener('change', () => {
                if (radioButton.checked) {
                    this.activateRenderer(rendererName);
                }
            });
        } else {
            Logger.logError('Unable to find radio button matching: ' + valueSelector)
        }
    }
}

activateRenderer

activateRenderer is the method that is called whenever a radio button has been checked. Calling this.readerView.setResponsiveRendererSelectionEnabled(true) will allow the ReaderView to automatically select renderers, based on the responsive view rules that were passed in when adding the renderer to the ReaderView.

private activateRenderer(rendererName: RendererName): void {
    if (rendererName === RendererName.RESPONSIVE) {
        this.readerView.setResponsiveRendererSelectionEnabled(true);
    } else {
        const renderer = this.readerView.getRendererByName(rendererName);
        if (renderer) {
            this.readerView.setActiveRenderer(renderer);
        } else {
            Logger.logError('Unable to find renderer with name: ', rendererName);
        }
    }
}

Integrating with the App

Changes to App.ts

Add a method in the App class to create the new RendererSwitcherView instance.

createRendererSwitcherView(rendererSwitcherContainer: HTMLElement): void {
     new RendererSwitcherView(this.readerView, rendererSwitcherContainer);
}

index.ts

In index.ts, after creating the app, call the new createRendererSwitcherView method.

// After const app = new App(...)
const rendererSwitcherElement = document.getElementById('renderer-switcher');
if (rendererSwitcherElement) {
    app.createRendererSwitcherView(rendererSwitcherElement);
} else {
    Logger.logError('Unable to find #renderer-switcher');
}

CSS

Add the following CSS to index.css to properly position the radio buttons and their labels.

#renderer-switcher {
    width: 100%;
}

#renderer-switcher label {
    display: block;
}

#renderer-switcher input {
    float: left;
}

Concepts

Engine Event

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

The ReaderView’s main responsibilities are rendering publication content and navigating in the publication.

Renderer

Renderers are used by a ReaderView to display publication content.

Responsive Renderer Selection

When responsive renderer selections is enabled, the rule provided when calling ReaderView.addRenderer() is used to evaluate when the renderer should be active. The rule can either a CSS media query, an implementation of the IResponsiveViewRule interface or a callback function.

If multiple renderers have been added with rules evaluate to true with the current configuration, the ReaderView will choose the renderer from those renderers that can use as much area of the viewport as possible.

If none of the renderers added to the ReaderView have matching rules, the ReaderView will choose the best fit from all renderers that have been added.

Calling ReaderView.setActiveRenderer() will cause responsive renderer selection to be disabled.

See IReaderView.addRenderer() in the API documentation for more information.