Highlights

Introduction

This tutorial will teach you how to create highlights from a selection in publications. You will create three different highlight styles. The highlights will be rendered on top of the publication content. Highlights will also be put in a list with clickable links to navigate the ReaderView to the location where the highlight was created. The highlights that are visible in the ReaderView will be marked as bold in the list.

Audience

Developer who knows typescript and knows what an EPUB is and has done the navigation tutorial.

Prerequisites

Set up tutorial environment + navigation

Not included

Other ReaderViewAnnotationLayer features such as click event handling.

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

Start with the code you wrote in the Basic navigation tutorial.

Highlight text

ReaderViewAnnotationLayer

A ReaderViewAnnotationLayer is used to render ReaderViewAnnotations on top of publication content. The ReaderView is responsible for creating annotation layers.

Create a new file named AppHighligter.ts and in that file create the class AppHighlighter that will be responsible for managing the highlights.

TYPESCRIPT

export class AppHighlighter {
  private readonly annotationLayer: IReaderViewAnnotationLayer;
  private latestSelectionEvent: ISelectionChangedEngineEvent | null = null;
  private readonly annotationToListItemMap: Map<IReaderViewAnnotation, HTMLLIElement> = new Map();
  private readonly createHighlightButton: HTMLElement;
  private readonly highlightListElement: HTMLElement;

  constructor(private readonly readerView: IReaderView, highlightsContainer: HTMLElement) {
    this.annotationLayer = this.readerView.createAnnotationLayer('highlights');
  }
}

And create an instance in your app.

TYPESCRIPT

class App {
  ...
  constructor(..., highlightsContainer: HTMLElement) {
    ...
    new AppHighlighter(this.readerView, highlightsContainer);
  }
}

Selection changed event

To highlight text snippets in a publication you first need to know that the user has made a range selection. The reading system emits a selectionChanged EngineEvent every time the selection has changed. You need to capture the selection event and store the selection data to use when the user clicks the create highlight button.

In the constructor add an engine event listener for selectionChanged.

TYPESCRIPT

constructor(...) {
  ...
  readerView.addEngineEventListener('selectionChanged', (event: ISelectionChangedEngineEvent) => {
    if (event.isRange) {
      this.latestSelectionEvent = event;
      AppHighlighter.enableButton(this.createHighlightButton);
    } else {
      this.latestSelectionEvent = null;
      AppHighlighter.disableButton(this.createHighlightButton);
    }
  });
}

private static enableButton(button: HTMLElement): void {
  button.removeAttribute('disabled');
}

private static disableButton(button: HTMLElement): void {
  button.setAttribute('disabled', '');
}

When the user deselects the text, event.isRange will be false. This lets you remove the selection data to avoid creating highlights from old selections.

Highlight creation button

You need to give the user a way to create a highlight after selecting a text snippet. In this tutorial you will use a <button> for creating highlights. You also need to create a <ul> element for showing the created highlights.

Add the following html in index.html.

HTML

<div id="highlights-container">
    <button id="create-highlight" disabled>Create highlight</button>
    <h4>Highlights (bold if visible in ReaderView)</h4>
    <ul id="highlight-list"></ul>
</div>

Get the container element in index.ts and pass it to the App class.

TYPESCRIPT

...
const highlightsContainer = document.getElementById('highlights-container');

if (viewElement && highlightsContainer && apiKey) {
  const app = new App(viewElement, apiKey, highlightsContainer);

In the AppHighlighter constructor, add the code to get the button and list element.

TYPESCRIPT

export class AppHighlighter {
  ...
  constructor(private readonly readerView: IReaderView, highlightsContainer: HTMLElement) {
    const highlightListElement = highlightsContainer.querySelector<HTMLUListElement>('#highlight-list');
    const createHighlightButton = highlightsContainer.querySelector<HTMLButtonElement>('#create-highlight');
    
    if (!createHighlightButton || !highlightListElement) {
      throw new Error('Unable to find #highlight-list or #create-highlight');
    }
    this.highlightListElement = highlightListElement;
    this.createHighlightButton = createHighlightButton;
    ...
  }
}

Highlight styling

To help you understand the different styling options, it is useful to know how the annotation layer is structured.

NONE

- <div class="colibrio-reader-view-annotation-layer"> which is rendered on top of all pages.
     - <div class="colibrio-reader-view-annotation-container"> which is rendered for each annotation.
         - One or more <div> elements, if the annotation refers to a range, or
         - One <div> element, if the annotation refers to a position in the content.

First you need to set the styles for the entire annotation layer. By specifying mix-blend-mode: multiply, we will be able to see the highlight but also the publication content underneath the highlight.

TYPESCRIPT

this.annotationLayer.setLayerOptions({
    layerStyle: {
        'mix-blend-mode': 'multiply'
    }
});

Then set a default style to be used by all annotations, simply adding a background color. This style can be overridden per annotation using IReaderViewAnnotation.setOptions().

TYPESCRIPT

this.annotationLayer.setDefaultAnnotationOptions({
    rangeStyle: {
        'background-color': '#b46ea6',
    }
});

Additional highlight styles

Let the user select what styling to use when creating a highlight. Add radio buttons to the highlights container in index.html.

HTML

<div id="highlights-container">
  <button id="create-highlight" disabled>Create highlight</button>
  <h4>Highlight style</h4>
  <form name="highlight-style">
    <div>
      <input type="radio" id="default" name="style" value="default" checked>
      <label for="default">Default</label>
    </div>
    <div>
      <input type="radio" id="dotted-underline" name="style" value="dottedUnderline">
      <label for="dotted-underline">Dotted underline</label>
    </div>
    <div>
      <input type="radio" id="boxed" name="style" value="boxed">
      <label for="boxed">Bounding box border</label>
    </div>
  </form>
  <h4>Highlights (bold if visible in ReaderView)</h4>
  <ul id="highlight-list"></ul>
</div>

The selected style value will be used to create the options to set on the annotation.

In index.css define a new .range-style--dotted-underline class that has a dotted bottom border and overrides the background color from the default annotation options.

CSS

.range-style--dotted-underline {
    /* Override the default annotation options. */
    background-color: transparent !important;
    border-bottom: 2px dotted red;
}

Create a function to get the IReaderViewAnnotationOptions from a radio button value.

TYPESCRIPT

private static getAnnotationOptionsFromStyle(style: HighlightStyle): IReaderViewAnnotationOptions | undefined {
  switch (style) {
    case HighlightStyle.Boxed:
      return {
        containerStyle: {
          'border': 'solid red 2px',
        },
        rangeStyle: {
          'background-color': 'transparent',
        }
      };

    case HighlightStyle.DottedUnderline:
      return {
        rangeClassName: 'range-style--dotted-underline'
      };

    case HighlightStyle.Default:
      return undefined; // Do not override the default options.
  }
}

The rangeStyle and rangeClassName attributes are used for styling an annotation when the annotation selects a range of text, as opposed to a single point. Each line of the text selected by the annotation will get the class and style defined in the options. When you instead want to style the bounding box surrounding the entire text selection, use containerStyle or containerClassName.

Creating annotation

Now you have all the components needed to create a highlight in your publication. First you need to make sure that the user has made a selection. The selection event contains a IContentLocation of the selected text. Use that IContentLocation to tell the annotation layer where to create the new annotation. To style the annotation use the previously created getStyleOptions function, pass the selected style value and set the resulting style options on the annotation.

You also want to keep track of the created annotations to show a list of the highlights and navigate to the location of the highlight in the publication.

TYPESCRIPT

createHighlight(style: HighlightStyle): void {
  if (this.latestSelectionEvent && this.latestSelectionEvent.contentLocation && this.latestSelectionEvent.selectionText) {
    const highlightAnnotation = this.annotationLayer.createAnnotation(this.latestSelectionEvent.contentLocation);

    const annotationStyleOptions = AppHighlighter.getAnnotationOptionsFromStyle(style);

    if (annotationStyleOptions) {
      highlightAnnotation.setOptions(annotationStyleOptions);
    }

    const highlightedText = AppHighlighter.shortenText(this.latestSelectionEvent.selectionText, 15);
    this.renderHighlightListItem(highlightAnnotation, highlightedText);

    this.readerView.clearContentSelection();
  }
}

private static shortenText(text: string, maxLength: number): string {
  if (text.length > maxLength){
    return text.substring(0, maxLength) + '...';    
  } else {
    return text;    
  }
}

To avoid creating many highlights at the same location, if the user accidentally presses the button again, call the readerView.clearContentSelection(). The engine will emit a selectionChanged event, and the event listener callback you defined before will be called, setting the currentSelection to null

Lastly, connect the create highlight button to the actual createHighlight function, by adding a click event listener in the AppHighligther constructor.

TYPESCRIPT

this.createHighlightButton.addEventListener('click', () => {
  // Get the selected radio button to use as style for the highlight
  const checked: HTMLInputElement | null = highlightsContainer.querySelector('input[name=style]:checked');
  const styleValue = checked !== null ? checked.value : 'default';
  if (AppHighlighter.isValidHighlightStyleValue(styleValue)) {
      this.createHighlight(styleValue);
  } else {
      Logger.logError('Unknown HighlightStyle value: ' + styleValue);
  }
});

Highlight list

Render highlight list items

When clicking on an item in the highlight list you want to make the publication navigate to the location of the highlight. Render the highlight list item as a anchor element with a click listener that tells the reader view to navigate to the locator from the highlight annotation.

TYPESCRIPT

private renderLink(text: string | null, locator: ILocator | null): HTMLAnchorElement {
  const link = document.createElement('a');
  link.href = '';
  link.innerText = text ?? '(missing text)';
  if (locator) {
    link.addEventListener('click', (e: MouseEvent) => {
      // Ignore the normal navigation and go to the locator
      e.preventDefault();
      this.readerView.goTo(locator)
        .catch(_ => console.log("Failed to go to " + locator.toString()))
    });
  }
  return link;
}

private renderHighlightListItem(highlightAnnotation: IReaderViewAnnotation<string>, highlightedText: string): void {
  const listItem = document.createElement('li');
  const link = this.renderLink(highlightedText, highlightAnnotation.getLocator());
  listItem.appendChild(link);

  listItem.appendChild(this.renderDeleteHighlightButton(highlightAnnotation));
  this.highlightListElement.appendChild(listItem);

  this.annotationToListItemMap.set(highlightAnnotation, listItem);
}

Add a button to delete the highlight. To delete the highlight, remove the list element from the document and use annotationLayer.destroyAnnotation() to remove the highlight from the annotation layer.

TYPESCRIPT

private renderDeleteHighlightButton(highlightAnnotation: IReaderViewAnnotation<string>): HTMLButtonElement {
  const button = document.createElement('button');
  button.className = 'delete-highlight-button';
  button.innerHTML = '&#9747;'; // X character
  button.addEventListener('click', () => this.deleteHighlight(highlightAnnotation));
  return button;
}

private deleteHighlight(highlightAnnotation: IReaderViewAnnotation<string>): void {
  this.annotationLayer.destroyAnnotation(highlightAnnotation);

  const listItem = this.annotationToListItemMap.get(highlightAnnotation);
  if (listItem) {
    listItem.remove();
    this.annotationToListItemMap.delete(highlightAnnotation);
  }
}

Detect annotations visible in the ReaderView

The framework emits the engine event annotationIntersectingVisibleRange when an annotation is visible in the ReaderView. The framework emits the engine event annotationOutsideVisibleRange when an annotation is no longer visible in the ReaderView. An annotation is initially in “not visible” state, meaning that you will receive a annotationIntersectingVisibleRange immediately when creating an annotation for content visible in the ReaderView.

Add the following code to toggle a class on highlight list items when they are visible in the ReaderView.

TYPESCRIPT

this.annotationLayer.addEngineEventListener('annotationIntersectingVisibleRange', evt => {
    const listItem = this.annotationToListItemMap.get(evt.annotation);
    listItem?.classList.add('highlight-list-item--in-visible-range');
});
this.annotationLayer.addEngineEventListener('annotationOutsideVisibleRange', evt => {
    const listItem = this.annotationToListItemMap.get(evt.annotation);
    listItem?.classList.remove('highlight-list-item--in-visible-range');
});

Add the highlight-list-item--in-visible-range CSS class to index.css.

CODE

.highlight-list-item--in-visible-range {
  font-weight: bold;
}

Wrap up

That’s it, now you know how to create highlights from a selection in publications with different styling. The highlights are displayed as a list and navigates to the page where the highlight is made. When a highlight is visible it will be marked as bold in the highlight list. Good job!

Concepts used in this tutorial

ContentLocation

An object describing a location within a publication. A ContentLocation has methods to extract information related to that location.

EngineEvent

An event emitted by the reading system engine.

Locator

A reference to a location in a publication.

ReaderViewAnnotation

A styled element at a location in a publication. Can contain custom data.

ReaderViewAnnotationLayer

A layer on top of the publication content, containing annotations. There can be many annotation layers.

Range selection

A selection where start and end differs, as opposed to a selection for a position.

ReaderView

Handles rendering and navigation.