Skip to content

@cbeer cbeer released this May 7, 2021


  • Blacklight 7 support
  • Bootstrap 4
  • Rails 6.1 support
  • New Arabic, Brazilian Portuguese, and Spanish translations, and improved RTL display
  • Accessibility improvements
  • Support bulk updates and bulk actions for adding/removing tags and public/private visibility to many exhibit items at once
  • New exhibit item indexing ETL framework, and other indexing improvements to provide better performance and visibility into the indexing background jobs for the exhibit builders
  • New browse groups for organizing long lists of browse categories


  • Include the site title in feedback emails (#2282)
  • Use the :long date format consistently (to include the year) (#2355)
  • Allow the engine configuration to limit which themes are available for a given exhibit (#2372)
  • Updated Exhibit cards on home page (#2481)
  • Improve rendering of browse categories, saved searches, and pages widgets (#2571)
  • Removes the require.js / almond.js conversion of ES6 JavaScript from amd to umd modules #2599
  • Improved OpenSeadragon ("ZPR") viewer styling
  • Add a query facet for public items
  • More granular exhibit export configuration for configuring what parts of an exhibit should be included in an export

Bug Fixes

  • Fix an issue with the analytics component and multiple analytics profiles (#2312)
  • Address a race condition when updating sidecar data (#2316 + #2320)
  • Have feedback emails come addressed from the service, not the feedback submitter (#2301)
  • Fix a navigation issue using the search result widget (#2347)
  • Fix an issue with empty custom field data being indexed as an empty string (instead of removing the data from Solr) (#2356)
  • Follow HTTP redirects when retrieving IIIF resources
  • Reserve page + exhibit slugs that conflict with application routing
  • Image uploads should be associated with an exhibit


In this major release, Spotlight 3 has updated its upstream dependencies to support the latest releases of Rails, Blacklight and Bootstrap. As such, it's important to review those upgrade guides and address deprecation warnings from your application either before or as part of upgrading to Spotlight 3.

  1. Review the Blacklight 7 upgrade guide
  2. Review the Bootstrap 3 to 4 migration guide for any local customizations
  3. Convert any local custom JavaScript from using require.js syntax to the umd version. See #2599

Additionally, there are some changes you need to make to your application to support new features or configurations in Spotlight 3:

  1. Add the SirTrevor initializer to your application
  2. Update local indexing code to use the new ETL framework (see below)
  3. Update your SearchBuilder to replace Spotlight::AccessControlsEnforcementSearchBuilder with Spotlight::SearchBuilder
  4. Install + run the new spotlight migrations: rake spotlight:install:migrations && rake db:migrate


Spotlight::SolrDocumentBuilder has been removed in Spotlight 3, and your Resource model is now responsible for all steps in the indexing process. Spotlight now provides an indexing pipeline framework to make it relatively easy to build your indexing rules into the resource.

Each resource class has indexing_pipeline method that defines the ETL steps for creating solr documents from your resource instance. In your local resource class, you'll want to add additional configuration to the pipeline to perform appropriate extract and load steps.

The pipeline source configuration is an array of extraction steps. These steps can return/yield one or more source objects that will be transformed later in the pipeline. In general, these objects should be 1:1 to the documents. By default, Spotlight assumes the resource object is the object to index, but e.g. if you had a resource instance that represented a collection containing 5 constituent object, the source would yield an object representing the collection and 5 additional objects for each part of the collection.

The pipeline transform configuration take the sources and turns it into a solr document-style hash. By default, Spotlight provides some steps that augment a document with fields that enable spotlight-specific features, but you'll need to add a transform step to appropriately transform your source object to any number of application-specific metadata fields.

Here's an example of overriding the indexing pipeline for a contrived resource class.

class MyResourceClass < Spotlight::Resource
  def self.indexing_pipeline
    @indexing_pipeline ||= super.dup.tap do |pipeline|
      # Override the default indexing pipeline to add our application-specific logic; in this case, the `#to_solr` method will be
      # called on the source object (which.. because we don't override the `pipeline.sources` at all.. is just the resource instance itself) 
      pipeline.transforms = [Spotlight::Etl::Transforms::SourceMethodTransform(:to_solr)] + pipeline.transforms

  def to_solr
    { id: id, title_field: xml_document.xpath('//title'), ...  }

Other examples of this new pattern include:

Other backwards compatibility notes

  • Spotlight 2 exhibit exports may not import cleanly into Spotlight 3 applications


Assets 2