Events

Mango API & Event Specifications

This document outlines the API methods and Event Bus events used to programmatically control the Mango viewer and monitor user interaction.

---

1. The Mango Controller Class

When integrating Mango as an npm library, the Mango class implements the ViewerApi interface.

Initialization

import { Mango } from '@mango/iiif-viewer';

const mango = new Mango({
  target: document.getElementById('viewer-root'),
  manifestId: 'https://example.com/iiif/manifest.json',
  config: {
    showThumbnails: true,
    language: 'en'
  }
});

Key Methods

Navigation

• getManifestId(): string | null - Returns the loaded IIIF manifest URL.
• setManifest(manifestId: string): void - Loads a new manifest.
• getCanvasIndex(): number - Returns the active canvas index.
• setCanvasByIndex(index: number): void - Navigates to a specific canvas page.

Viewport & 3D Controls

• getViewBox(): ViewBox | null - Gets coordinates of the current 2D zoom window.
• setViewBox(box: ViewBox): void - Sets coordinates and zooms/pans the canvas.
• setModelPose(pose: ModelPose, options?: ModelPoseOptions): void - Transition the camera position of a 3D model.

Audio & Video Controls

• play(): void - Start media playback.
• pause(): void - Pause media playback.
• seekTo(time: number): void - Seek to a timestamp (in seconds).

---

2. The Central Event Bus

The viewer communicates changes by publishing events to an internal EventBus.

Subscribing to Events

// Subscribe to canvas changes
const unsubscribe = mango.on('pageChange', (payload) => {
  console.log(`Navigated to canvas: ${payload.canvasId} (Index ${payload.index})`);
});

// Clean up listener later
unsubscribe();

Core Events Catalogue

Event Name	Payload Type	Description
manifestChange	{ manifestId: string }	Emitted when a new manifest begins loading.
pageChange	{ canvasId: string; index: number; label?: string }	Emitted when navigating to another canvas.
zoomChange	{ zoom: number; viewBox: ViewBox }	Emitted when the 2D image is zoomed.
mediaPlay	{ canvasId: string; time: number }	Emitted when audio/video playback starts.
`mediaTimeUpdate``	{ canvasId: string; time: number; duration?: number }	Emitted periodically during AV playback.
annotationSelect	{ id: string; annotation?: ResolvedAnnotation }	Emitted when clicking a visual annotation region.
pluginError	{ pluginId: string; phase: 'init'|'destroy'; message: string }	Emitted if a plugin lifecycle method throws an error.