Skip to content

boston-library/blacklight_iiif_search

BranchesTags

Repository files navigation

Blacklight IIIF Search

CI Workflow

A plugin that provides IIIF Content Search functionality for Blacklight-based applications.

IIIF Content Search is an API specification for searching the full text of a resource that is described by a IIIF Presentation API manifest.

When installed, this plugin provides an endpoint in your Blacklight app that will return a JSON response conforming to IIIF Content Search API v. 1.0.

By integrating the URL for this service into your IIIF Presentation manifests, clients/viewers that support the IIIF Content Search API (such as the Universal Viewer) will be able to provide functionality for searching within a resource and displaying results.

Prerequisites

This plugin assumes:

  1. You have a working Blacklight application, with Solr as the search index
  2. You have items with full text (e.g. scanned books, newspapers, etc.) in your Solr index
  3. The text for these items is indexed in Solr
  4. Each page has its own Solr record, with the corresponding text in a discrete field
    • the text field must be indexed
    • if search term highlighting is desired, the text field must be indexed and stored
  5. The relationship between page records and their parent book/volume/issue/etc records is indexed in Solr

Blacklight/Solr Version Compatibility:

blacklight_iiif_search version works with Blacklight tested with Solr
3.0 ~> 8.0 >= 7.0 to < 9.*
2.0 ~> 7.0 7.*
1.0 >= 6.3.0 to < 7.* 7.*

Installation

Add Blacklight IIIF Search to your Gemfile:

gem 'blacklight_iiif_search'

Run the install generator, which will copy over some initial templates, routes, and configuration:

$ rails generate blacklight_iiif_search:install

The generator:

  • Adds some configuration settings to app/controller/catalog_controller.rb
  • Adds the IiifSearchBuilder class to app/models
  • Adds routing to config/routes.rb
  • Injects some configuration into solr/conf/schema.xml and solr/conf/solrconfig.xml to support contextual autocomplete (To skip the Solr changes, run the install command with skip-solr flag.)

After install, you'll probably need to adjust the iiif_search settings in CatalogController:

Config option Description
full_text_field The Solr field where the OCR text is indexed/stored.
object_relation_field The Solr field where the parent/child relationship is stored.
supported_params An array of IIIF Content Search query parameters supported by the search service. (Note: motivation, date, and user are not currently supported.)
autocomplete_handler The value of the @name attribute for the Solr <requestHandler name="/#{autocomplete_handler}"> in solrconfig.xml that handles autocomplete suggestions.
suggester_name The value of the <str name="name">#{suggester_name}</str> element for the Solr in solrconfig.xml that handles autocomplete suggestions.

See below for additional customization options.

Basic Usage

The search service will be available at:

http://host:port/catalog/:id/iiif_search

There is a solr_document_iiif_search route helper that can be called to construct a path or URL to the search service in your app. For example:

solr_document_iiif_search_url('abcd1234', {q: 'blacklight'})

Would return:

http://host:port/catalog/abcd1234/iiif_search?q=blacklight

The autocomplete service will be available at: