Hello world

Introduction

This tutorial will teach you how to set up a Colibrio Reading System, load an EPUB publication from a file and rendering the publication in a ReaderView.

Audience

Typescript developers. No need for prior Colibrio Reader Framework needed.

Prerequisites

Set up tutorial environment

Not included

How to load other formats, than EPUB, such as PDF or W3C Audiobooks.

Full code example

For reference, you can find the full code example in the Web framework tutorials 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

To follow this tutorial, please check out the hello-world project in the Web framework tutorials repository. The text will explain the different parts of the code and give you some context on how to use Colibrio Reader Framework.

Load Publication

Set up reading system

The ReadingSystemEngine is the main entry point to the Colibrio Reading System. In this example you will use it to load publications and create a ReaderView.

TYPESCRIPT

const readingSystemOptions: IReadingSystemEngineOptions = {
    licenseApiKey: licenseApiKey
};

this.readingSystemEngine = new ReadingSystemEngine(readingSystemOptions);

A License Key is provided to you by Colibrio when you get access to the framework.

Loading a file using the HTML input element

In index.html, you need a way to get a file. Use a file <input> element:

HTML

<input id="file-select-input" type="file" accept="application/epub+zip, *.epub"/>

And the corresponding code to get the File from the input element:

TYPESCRIPT

const fileSelect = document.getElementById('file-select-input');
if (fileSelect) {
    fileSelect.addEventListener('change', async (ev) => {
        const target = ev.target as HTMLInputElement;
        if (target.files) {
            const epubFile: File = target.files[0];
        }
    });
}

Add support for EPUBs

Add an EpubFormatAdapter to the reading system to add support for EPUB publications. The reason you need to explicitly add support for a format is simply to keep the code size as small as possible and only load modules you need. The Colibrio Reading System provides other FormatAdapters, but for now you only need the EpubFormatAdpater.

TYPESCRIPT

this.readingSystemEngine.addFormatAdapter(new EpubFormatAdapter());

To load an EPUB publication you need an EpubOcfResourceProvider. The ResourceProvider is used by the reading system to fetch resources from the the publication file. Create a ResourceProvider right after the format adapter code.

TYPESCRIPT

const ocfResourceProvider = await EpubOcfResourceProvider.createFromBlob(epubFile);
const epubPublication = ocfResourceProvider.getDefaultPublication();

An EPUB Open Container Format (OCF) container can host many publications, where the default publication is the first defined in the container.xml file. For this example use the default publication.

Process the publication

The next step is to load the publication into the ReadingSystemEngine. The ReadingSystemEngine locates the correct FormatAdapter and uses it to convert the publication to a ReaderPublication. A ReaderPublication is a version of the publication that can be rendered by the ReadingSystemEngine.

TYPESCRIPT

if (epubPublication) {
    const licenseOptions = {
      userToken: await SimpleObfuscation.obfuscate(this.userId),
      publicationToken: await SimpleObfuscation.obfuscate(epubPublication.getHashSignature())
    };
    return this.readingSystemEngine.loadPublication(epubPublication, undefined, licenseOptions);
}

It is important to use correct unique user and publication tokens to adhere to the license agreement!

License options

The license options are used to keep track of the usage according to your license agreement.

The user token should be unique for each user of your application, e.g. an obfuscated version of a user id used in your system.

The publication token should be unique for each publication used in your application, e.g. an obfuscated version of the publication hash or any other unique identifier for a publication used in your system.

The obfuscation is a way to anonymize the tokens and is needed as the reading system engine sends the tokens to the Colibrio license server. In this example we have provided a simple obfuscation module that returns a SHA-1 hashed hexadecimal string, but you can use what you feel best suits your needs.

In order to run the tutorial code, add a userId string with a username of a made up user to your index.ts and pass to the App. The hash signature of the EPUB publication can be used as input for the publication token.

Render the publication

Create ReaderView

The ReaderView is the part responsible for rendering the publication. Create a ReaderView and add a Renderer.

TYPESCRIPT

const readerView = this.readingSystemEngine.createReaderView();

The ReaderView uses a Renderer to render the publication content. Colibrio provides a number of Renderers, in this example we will use the FlipBookRenderer.

TYPESCRIPT

readerView.addRenderer(new FlipBookRenderer());

Create HTML element

The ReaderView needs to know where to render the publication content, so create an HTML element. The element must have a width and height to allow the reading system engine to calculate resizing of images and reflowing texts.

Create a viewport <div> in index.html

HTML

<div id="readingsystem-viewport"></div>

Add a width and height for the reading system viewport in index.css

CSS

#readingsystem-viewport {
    width: 90vw;
    height: 60vh;
    position: relative;
}

Then tell the ReaderView to use the viewport element for rendering.

TYPESCRIPT

const viewElement = document.getElementById('readingsystem-viewport');
readerView.renderTo(viewElement);

Refresh

The reading system engine gives you control over when to refresh the content and size of the reader view. The reason that the reading system engine does not refresh the content automatically is that there are situations where you want to keep the old rendering. One example of this is when the keyboard is opened on a mobile device, where you might want to have it on top of the content instead of changing the layout of the publication.

To add a basic refresh when the window is resized first create a function in the App.

TYPESCRIPT

refresh() {
  this.readerView.refresh();
}

Then create an event listener in index.ts

TYPESCRIPT

window.addEventListener('resize', () => app.refresh());

Choose which part of the publication to render

Lastly, before anything is rendered, you need to tell the reader view which part of the publication to render. In this example, we will just render the beginning of the publication. Navigating to other parts of the publication is done using other methods available in the ReaderView.

TYPESCRIPT

readerView.goToStart();

That concludes this tutorial. You should now have an app where you can load an EPUB and display the first page on the screen.

Concepts used in this tutorial

EPUB

A file format for packaging and distributing digital books.

ReadingSystemEngine

The entry point to the Colibrio Reading System. The engine loads publications and creates ReaderViews.

ReaderView

Handles rendering and navigation.

FormatAdapter

Knows how to process specific publication formats. Produces ReaderPublications.

EpubFormatAdapter

A FormatAdapter that handles the EPUB format. Produces EpubReaderPublication

Renderer

Responsible for how a publication is rendered in a ReaderView

FlipbookRenderer

Renders a publication in a way that resembles a book, with two pages displayed as a spread.

ResourceProvider

An interface that allows the reading system to load resources from various sources.

EpubOcfResourceProvider

A ResourceProvider with knowledge of the file structure of the EPUB OCF format.

OCF

EPUB Open Container Format. I file format encapsulating a set of related resources that comprise a EPUB publication. https://www.w3.org/publishing/epub3/epub-ocf.html

Publication

Contains the metadata and content of a publication parsed from the source, but not further processed by the system.

ReaderPublication

A version of a publication processed to be rendered in a ReaderView.

EpubReaderPublication

An EPUB specific ReaderPublication, with extra functions related to the capabilities of the EPUB format.

License Options

The user token should be unique for each user of your application. The publication token should be unique for each publication for each publication used in your application. The system sends the tokens to the Colibrio license server and both tokens needs to be anonymized.