Adding PDF support

Introduction

This tutorial will teach you how to add support for PDF publications. You will also learn how to dynamically import modules, since the PDF module is quite big and there is no point in loading it unless the user actually wants to read a PDF.

Audience

Typescript developers.

Prerequisites

Basic navigation  

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

The code in this tutorial builds on the code from the basic navigation tutorial.

Create publication

Loading a PDF publication is very similar to loading an EPUB publication. Instead of using a EPUB format specific EpubOcfResourceProvider to create a ResourceProvider and then use that to create a publication, you can directly use the PdfPublication to create a publication. Start with creating a loadPdf method in your App.ts

private async loadPdf(pdfFile: Blob): Promise<void> {
    await this.loadPdfFormatAdapter();

    const pdfModule = await App.loadCorePdfModule();
    const pdfPublication = await pdfModule.PdfPublication.createFromBlob(pdfFile)
    return this.loadAndSetReaderPublication(pdfPublication);
}

As you can see, the PDF modules are loaded on demand when loadPdf is called. More about dynamic imports later. First finish up the code for loading publications.

Reuse the code for loading a ReaderPublication that you wrote for the EPUB parts and move to a new method, that can be used by both PDF and EPUB loading.

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([]);
      await this.readingSystemEngine.unloadPublication(this.readerPublication);
    }
    this.readerPublication = await this.readingSystemEngine.loadPublication(publication, undefined, licenseOptions);
    this.readerView.setReaderDocuments(this.readerPublication.getSpine());
  } else {
    return Promise.reject('No publication found in the provided file.');
  }
}

Dynamic imports

The PDF module, as well as the EPUB module, is fairly big and can take some time to load. If you don’t know that both formats will be used, it might be better to use dynamic imports to load the modules when they are needed.

For each format you need to load a format adapter module and a core publication module. Loading and adding the format adapter to the ReadingSystemEngine adds support for rendering the format and the core publication module contains code for loading the file and extracting metadata.

Create the methods for importing the modules for both PDF and EPUB.

private static loadCorePdfModule() {
  return import('@colibrio/colibrio-reader-framework/colibrio-core-publication-pdf');
}

private static loadPdfFormatAdapterModule() {
  return import('@colibrio/colibrio-reader-framework/colibrio-readingsystem-formatadapter-pdf');
}

private static loadCoreEpubModule() {
  return import('@colibrio/colibrio-reader-framework/colibrio-core-publication-epub');
}

private static loadEpubFormatAdapterModule(){
  return import('@colibrio/colibrio-reader-framework/colibrio-readingsystem-formatadapter-epub');
}

If you have imports of those modules at the top of the file, remove those.

Format adapter

To add support to render PDFs, add a PDF format adapter. The PDF format adapter holds information on how to handle the PDF format. You only want to load a format adapter once, not every time the user opens a new publication. One way to do this is by keeping track of the module loading Promise, any subsequent calls after a successful loading returns the original promise. This also ensures that the format adapter only is added once after loaded.

Create a method using the loadPdfFormatAdapterModule method and then add the format adapter to the reading system engine.

private loadPdfFormatAdapter(): Promise<void> {
  if (!this.pdfFormatAdapterPromise) {
    this.pdfFormatAdapterPromise = App.loadPdfFormatAdapterModule()
          .then(pdfAdapterModule =>
            this.readingSystemEngine.addFormatAdapter(
              new pdfAdapterModule.PdfFormatAdapter()
            )
          );
  }
  return this.pdfFormatAdapterPromise;
}

Also add another method for the EPUB format adapter

private loadEpubFormatAdapter(): Promise<void> {
  if (!this.epubFormatAdapterPromise) {
    this.epubFormatAdapterPromise = App.loadEpubFormatAdapterModule()
          .then(epubFormatAdapterModule =>
            this.readingSystemEngine.addFormatAdapter(
              new epubFormatAdapterModule.EpubFormatAdapter()
            )
          );
  }
  return this.epubFormatAdapterPromise;
}

Load publication

Replace the existing loadEpub method with a new method, similar to the loadPdf method.

private async loadEpub(epubFile: Blob): Promise<void> {
  await this.loadEpubFormatAdapter();

  const epubModule = await App.loadCoreEpubModule();
  const ocfResourceProvider = 
    await epubModule.EpubOcfResourceProvider.createFromBlob(epubFile);
  const pdfPublication = await ocfResourceProvider.getDefaultPublication();
  return this.loadAndSetReaderPublication(pdfPublication);
}

Detecting the publication type

To know what method to use when loading a publication, you need a way to detect the type of the file loaded. Colibrio provides an API for detecting media types, called MediaTypeDetector. Use this API to check if a publication is an EPUB (application/epub+zip) or a PDF (application/pdf). Note that you also need to accept application/zip for EPUBs because it’s not uncommon for EPUBs to be packaged with the wrong mimetype.

Create a method called loadPublication that takes any file as input and figures out what the publication type is before passing it to the corresponding load method.

async loadPublication(publicationFile: Blob): Promise<void> {
  const publicationType = await MediaTypeDetector.detectFromBlob(publicationFile);

  if (publicationType === MediaType.APPLICATION_EPUB_ZIP ||
      publicationType === MediaType.APPLICATION_ZIP) {
    return this.loadEpub(publicationFile);
  } else if (publicationType === MediaType.APPLICATION_PDF) {
    return this.loadPdf(publicationFile);
  } else {
    return Promise.reject("Unsupported file type: " + publicationType);
  }
}

Changes to index.ts

In the change event listener for the file input element, replace the usage of loadEpub with the more generic loadPublication that you’ve just created.

fileSelect.addEventListener('change', async (ev) => {
  const target = ev.target as HTMLInputElement;
  if (target.files) {
    const publicationFile: File = target.files[0];
    await app.loadPublication(publicationFile);
    await app.goToStart();
  }
});

Changes to index.html

The only change to index html is to add the PDF filetype to the accept attribute on the file input element. It should look something like this:

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

Conclusion

That is it, now you know how to dynamically load the modules needed for different publication formats and how to add support for PDF.

Concepts used in this tutorial

Dynamic Imports

A function to dynamically import javascript modules. Read more at MDN.

Format Adapter

Knows how to process specific publication formats. Produces ReaderPublications.

Resource Provider

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

Reader Publication

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

Reading System Engine

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