Upgrading to Blacklight 8

Blacklight 8 includes some backwards-incompatible changes. Follow this guide to upgrade a Blacklight 7 application to Blacklight 8.

Ensure your local application has a passing test suite. If needed, add automated tests for any important functionality, to make it obvious when something is broken.
Upgrade to the latest 7.x release so you can see any recent deprecation warnings.
Take note of any deprecation warnings originating from Blacklight in the logs and make the suggested changes.
Upgrade to Blacklight 8 and follow the Upgrade Notes below.

Plugin status against Blacklight 8

To test a plugin and validate it Run the plugin with the latest version of blacklight/main.

Tested and known to work

TODO: Add to this list the release of gem compatible with BL8

Tested and in need of upgrade

blacklight_range_limit - the javascript for the histogram does not work, needs attention. Note that Bootstrap slider claims to only work with bootstrap 4, although it seems to work with Bootstrap 5.
blacklight_iiif_search - owned by boston-library, has a dependency on Blacklight 7
blacklight_advanced_search - release needed

Testing in progress

geoblacklight - a number of UI issues, in progress PR open

Not yet tested

There are none

Upgrade Notes

@document_list is no longer provided by Blacklight, because Blacklight::SearchService#search_results now returns a single value rather than a tuple: https://github.com/projectblacklight/blacklight/blob/2430033de0f8c54ef7407e28228b3702f1fd3e0a/app/services/blacklight/search_service.rb#L24 This instance variable was previously a ActiveSupport::Deprecation::DeprecatedObjectProxy. For the documents use response.documents.
Blacklight::SearchService#fetch now returns just the document/s, rather than the solr response and the document/s.
Remove component: true configuration from add_facet_field in CatalogController
Remove //= require blacklight/blacklight from your sprockets javascript manifest (app/assets/javascripts/application.js). It is now included by the base layout.
If you previously used a partials configuration in CatalogController like this: config.show.partials = [:index_header, :thumbnail, :index] and some of the partials were provided by Blacklight, this may no longer work as the partials have been replaced by the DocumentComponent (https://github.com/projectblacklight/blacklight/blob/main/app/components/blacklight/document_component.rb) You can replace the DocumentComponent by setting config.show.document_component = MyDocumentComponent. You could also copy the partials from the release-7.x branch into your local application.
If you override app/views/catalog/_show_main_content.html.erb, please note that it has changed significantly. Notably, it now renders the DocumentComponent and no longer calls render_document_partials
If you override app/views/catalog/facet.html.erb, please note that it has changed significantly. Notably, it now renders the Blacklight::FacetComponent and no longer calls render_facet_limit
app/views/catalog/_constraints_element.html.erb is no longer present. Overriding it has no effect.
Explicitly pass the documents to the render_document_index method. See https://github.com/projectblacklight/blacklight/pull/2530/files for an example.
Add config.bootstrap_version = 4 to app/controllers/catalog_controller.rb in the configure_blacklight do |config| block to ensure the close button works for flash messages with Bootstrap 4
remove the lines below from your SolrDocument. If you have customized the emails or sms that you send to users, you can recreate those customizations by updating email_fields or sms_fields configurations in your catalog controller and/or subclassing MetadataFieldPlainTextLayoutComponent. See PR #2803 for more details.
```
   # Email uses the semantic field mappings below to generate the body of an email.
   SolrDocument.use_extension(Blacklight::Document::Email)

   # SMS uses the semantic field mappings below to generate the body of an SMS email.
   SolrDocument.use_extension(Blacklight::Document::Sms) 
```
render_hash_as_hidden_fields has been replaced by Blacklight::HiddenSearchStateComponent
convert_to_search_state has been removed. Just use search_state
start_over_path is no longer a helper. It has been moved to Blacklight::StartOverButtonComponent
if you customized app/view/catalog/_index_header_default.html.erb it must move into a custom component. This component should then be set in the index config. `config.

Accumulate backwards breaking changes here so they can be turned into upgrade path steps in the document above

Plugin Upgrade Scenarios

Adding elements to Constraints

"Constraints" is what Blacklight calls the area above search results that tells you all the queries/limits/filters at play in your search, and lets you remove them individually. Plugins often want to add elements to this "constraints" area.

In pre-8 Blacklight they did this by over-riding helper methods either render_constraints or render_constraints_filters to call super and concatenate their own additional content.

In BL 8 all the constraints are rendered by app/view/catalog/_constraints.html.erb, which renders the following components:

Blacklight::ConstraintsComponent this used to be render_constraints
Blacklight::ConstraintLayoutComponent this used to be render_constraints_element

In Blacklight 8 plugins should provide custom facet behavior through the add_facet_field config option. The label and item_presenter will be used to create the constraint elements.

Here is an example from geoblacklight.

Blacklight's facet field configuration

Change the way the query constraint is rendered

Unlike "adding element to constraints" above, only one thing at a time can do this, there's only one "query" constraint. But plugins have sometimes done this, and so have local apps.

In pre-8 Blacklight they did this by over-riding the render_constraints_query helper method.

In Blacklight 8 the constraints query is rendered by the query_constraint_component argument (default Blacklight::ConstraintLayoutComponent), which is passed into the Blacklight::Constraints component. To customize, provide a different component by overriding app/views/catalog/_constraints.html.erb. Have it render a Blacklight::ConstraintsComponent initialized with your custom query constraint component

Render Constraints in a new page in plugin or app

A plugin or app may want to render search constraints on it's own new page.

In pre-8 Blacklight it called the helper method render_constraints to render the constraints including any customizations added by plugins or local app, as above.

In Blacklight 8 a location wanting to render constraints should render a constraints component, which ordinarily behaves according to current catalog configuration. By default this is Blacklight::ConstraintsComponent, but the component can be configured by a local app. See app/view/catalog/_constraints.html.erb for how to look up currently configured constraints component and what arguments to call it with.