Transient Highlights

You can use the Transient Highlighting API (ITransientHighlightManager) to create transient highlights and annotations, which the Review Interface doesn't persist. This API supports translating these highlights to and from objects that persist them outside of the Review Interface. The core viewers in the Review Interface expose this API and additional utility methods. Custom viewers may not expose this API.

This page contains the following information:

• Highlight sets
• Highlights
• Interact with highlights
• Draw highlights
• Highlight events

Code samples

When reviewing the code samples provided on this page, assume they're run from inside a handler for the ReviewInterfaceEventType.ApiReady event. The following code sample illustrates this structure:

(function (parameters) {
  var config = {
    name: "Transient Highlight Example Extension",
    id: "relativity.examples.transient.highlights",
    lifecycle: {
      apiready: function (api) {
        // Transient highlight code will be here.
      },
    },
  };
})(params);

Highlight sets

Before adding highlights, you need to create a highlight set with HighlightSetMemento. Use the createSet method, which returns a setId for use with other methods. See the following code sample:

const setId =
  api.viewer.mainCollection.activeViewer.transientHighlight.createSet();

Use the serialize method to translate the object represented by the setId variable to one that persists state outside the Review Interface. This method returns a HighlightSetMemento object, which includes information about the set and the highlights that it contains. In the following code sample, the setId returned by the createSet method is now passed to the serialize method:

const set =
  api.viewer.mainCollection.activeViewer.transientHighlight.serialize(setId);

Highlights

After you create a highlight set, you can add highlights to it. The following sections describe how to create a highlight:

• Create a range
• Retrieve the page height and width
• Define a highlight config object
• Create a highlight
• Delete a highlight

Create a range

Create a range that represents the highlight.

Note: Depending on the document type, it may support only certain types of ranges. Use the checkHasFeature method to determine whether a document supports a specific range type. For more information, see Set the selection mode.

Use one of the following memento types for a range:

• CellRangeMemento
• RectRangeMemento
• TextRangeMemento

The core viewers expose the following methods for creating a range:

• createCellRange
• createRectRange
• createTextRange

Note: The pixel (0,0) is at the top left corner of the page. The axis values increase as you move to the right and bottom of the page.

The following code sample illustrates how to create a RectRangeMemento on the first page of a document. The range starts at pixel (100,100) and ends at pixel (200,200):

const rectRange = api.viewer.mainCollection.activeViewer.createRectRange(
  0,
  100,
  100,
  200,
  200,
  "px"
);

Retrieve the page height and width

To retrieve the page height and width, use the getPageHeight and getPageWidth methods. Optionally, pass a zero-based index to these methods as follows:

• Index - If you pass an index, the results are for the page at the given index.
• No Index - If you don't pass an index, the results are for the currently visible page.

// Get height of the visible page.
const height = api.viewer.mainCollection.activeViewer.getPageHeight();
// Get width of the page at index 2.
const width = api.viewer.mainCollection.activeViewer.getPageWidth(2);

Define a highlight config object

To define the look and behavior of a highlight, create a PartialHighlightConfig object. This object includes multiple options that control the styling of the highlight, and its behavior, such as whether it can be moved, deleted, and so on.

The following code sample illustrates a config object for a rectangular redaction with default styling in black. The user can delete, move, and resize the redaction.

const rangeconfig = {
  activationMode: "box",
  visible: true,
  redaction: true,
  inverse: false,
  sticky: true,
  fullPage: false,
  enableDelete: true,
  enableMove: true,
  enableResize: true,
};

Create a highlight

To create a highlight, use the addHighlight method. Pass the ID for highlight set, the range, and the configuration object to it. This method returns a promise that resolves to a HighlightMemento.

const highlight =
  await api.viewer.mainCollection.activeViewer.transientHighlight.addHighlight(
    setId,
    rectRange,
    rangeconfig
  );

Delete a highlight

To delete a highlight, use the removeHighlight method. Pass the setId and the highlightId on the object returned by addHighlight method:

api.viewer.mainCollection.activeViewer.transientHighlight.removeHighlight(
  setId,
  highlight.highlightId
);

Interact with highlights

You can define how users interact with highlights by setting the selection mode for the viewer, and programmatically selecting ranges in the document or retrieving the currently selected highlights.

See the following sections:

• Set the selection mode
• Select cell ranges
• Retrieve highlights

Set the selection mode

Set the selection mode for the viewer so that users can interact with highlights by selecting, resizing, moving, and performing other tasks.

The following table lists selection modes:

Mode	Description
rect	Allow interaction with highlights created with a RectRangeMemento.
cell	Allow interaction with highlights created with a CellRangeMemento.
text	Allow interaction with highlights created with a TextRangeMemento, and with the text in the document, such as selecting, copying, and pasting it.
none	Disable all highlight interaction.

Track the mode that is active in the viewer and reset it as needed. Also, verify that the document viewed by the user supports the mode that you want to set.

To check the current selection mode, use the getSelectionMode method for the viewer:

const currentMode = api.viewer.mainCollection.activeViewer.getSelectionMode();

To set a new selection mode, use the setSelectionMode method:

api.viewer.mainCollection.activeViewer.setSelectionMode("rect");

To verify that the document supports a specific mode, use the checkHasFeature method. Except for none, the modes listed in the table each have a corresponding string that you can pass to the checkHasFeature method.

Mode	Feature
rect	rectselection
cell	cellselection
text	textselection

The following code sample illustrates how to use checkHasFeature method:

const hasFeature =
  api.viewer.mainCollection.activeViewer.checkHasFeature("rectselection");

Select ranges

To programmatically select ranges, use one of the following methods:

• selectCellRange
• selectRectRange
• selectTextRange

These methods take a range memento object and return true when the active selection has changed. See Create a range.

The following code sample illustrates how to select a rect range:

const selectionChanged =
  api.viewer.mainCollection.activeViewer.selectRectRange(rectRange);

To get the currently selected range, use the selectionRange method. It returns the appropriate range memento type based on the current selection, or undefined when there's no selection.

const selection = api.viewer.mainCollection.activeViewer.selectionRange();

Retrieve highlights

You can retrieve highlights that are currently selected in a document by a user or programmatically. Use the getSelectedAnnotations method, which returns an array of the selected HighlightMemento objects.

const selectedHighlights =
  api.viewer.mainCollection.activeViewer.transientHighlight.getSelectedAnnotations();

Draw highlights

You can implement functionality that allows the users to draw highlights by pointing, clicking, and dragging.

First, set the appropriate modes. See Set the selection mode.

Next, call the enableAutoHighlight method by passing the setId and a config object. See Define a highlight config object.

api.viewer.mainCollection.activeViewer.transientHighlight.enableAutoHighlight(
  setId,
  rangeconfig
);

The auto highlight feature remains enabled until you explicitly disable it. Use the disableAutoHighlight method as follows:

api.viewer.mainCollection.activeViewer.transientHighlight.disableAutoHighlight();

Highlight events

For highlights, you can register listeners against the following set-level events:

• onadd - fires when a highlight is added to a set. Its callback function interface is IHighlightSetListenerAdd.
• onmove - fires when a highlight in a set is moved. Its callback function interface is IHighlightSetListenerMove.
• onremove - fires when a highlight in a set is removed. Its callback function interface is IHighlightSetListenerRemove.

These functions take the corresponding callback function and the setId for the set that you want to register the handlers against. See the following code samples:

const addhandler = (set, highlights) => {
  console.log(`${highlights.length} highlights added to set ${set.id}`);
};
api.viewer.mainCollection.activeViewer.transientHighlight.onadd(
  setId,
  addhandler
);

const movehandler = (set, highlight, oldrange) => {
  console.log(`${highlight.highlightId} moved in set ${set.id}`);
  console.log(`Old top: ${oldrange.top}`);
};
api.viewer.mainCollection.activeViewer.transientHighlight.onmove(
  setId,
  movehandler
);

const removehandler = (set, highlights) => {
  console.log(`${highlights.length} highlights removed from set ${set.id}`);
};
api.viewer.mainCollection.activeViewer.transientHighlight.onremove(
  setId,
  removehandler
);

The following methods unregister the event handlers:

• offadd
• offmove
• offremove

See the following code samples:

api.viewer.mainCollection.activeViewer.transientHighlight.offadd(
  setId,
  addhandler
);
api.viewer.mainCollection.activeViewer.transientHighlight.offmove(
  setId,
  movehandler
);
api.viewer.mainCollection.activeViewer.transientHighlight.offremove(
  setId,
  removehandler
);