How to Simultaneously Specify Canvas and Highlight Search Terms in Mirador 4

Introduction

I implemented functionality in Mirador, a widely used IIIF (International Image Interoperability Framework) viewer, to meet the following requirements:

1. Display the canvas (page) specified by URL parameters on initial load
2. Highlight search terms within the specified canvas

This article shares the approach and implementation method for achieving these requirements.

Exploring Approaches

defaultSearchQuery Option

In Mirador 4, you can automatically execute a search at initialization by specifying the defaultSearchQuery option in the window settings:

This option is a convenient feature that automatically executes a search, but for this use case, the following points needed to be considered:

1. Page navigation control - Since the specification automatically navigates to the page of the first hit when a search is executed, additional control is needed if you want to stay on the page specified by canvasId
2. Knowing when the search completes - Since the search is executed asynchronously, monitoring Redux state is needed if you want to perform processing after completion

A More Direct Approach

After consideration, I adopted an approach that directly uses the receiveSearch action. With this approach:

1. Call the Search API directly to get only hits matching the specified canvas
2. Build a response in IIIF Search API format
3. Register it as search results in Mirador using the receiveSearch action

This allows leveraging Mirador’s search highlight feature as-is while maintaining the display of the specified canvas.

Implementation

1. Function to Get Hits from the Search API

This implementation dynamically retrieves the IIIF Search API endpoint from the manifest’s service property. This allows it to work with any IIIF-compliant server.

2. Mirador Initialization and Highlight Registration

Key Points

1. Accessing Mirador’s Action Functions

In Mirador 4, action functions can be accessed directly from the global object:

Note that you access them directly as Mirador.receiveSearch, not through Mirador.actions.

2. IIIF Search API Format Response

The JSON passed to receiveSearch must conform to the IIIF Search API 1.0 format:

3. CompanionWindow Placement

The placement of the search panel can be controlled with the position parameter:

• left: Left side (same position as the metadata panel)
• right: Right side

A natural layout is metadata on the left and search results on the right.

Conclusion

By directly calling the receiveSearch action, the following benefits were achieved:

1. Canvas display control - Can add highlights while displaying the specified canvas on initial load
2. Immediate highlight display - Highlights are displayed immediately because search results are registered directly
3. Panel placement control - The position of the search panel can be freely configured

This method leverages Mirador’s Redux store mechanism and allows for flexible customization.

Reference Links

• Mirador GitHub Repository
• IIIF Search API 1.0
• Creating annotation in Mirador programmatically - Stack Overflow