Upgrading to Blacklight 9

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

1. 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.

2. Upgrade to the latest 8.x release so you can see any recent deprecation warnings.

3. Take note of any deprecation warnings originating from Blacklight in the logs and make the suggested changes.

4. Upgrade to Blacklight 9 and follow the Upgrade Notes below.

Plugin status against Blacklight 9

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

Tested and known to work

1. blacklight-hierarchy
2. blacklight_range_limit - Tested and working in blacklight 9.x pre-releases as of blacklight_range_limit 9.0
3. blacklight_dynamic_sitemap
4. blacklight-gallery
5. arclight https://github.com/projectblacklight/arclight/pull/1596 (needs a release cut)

Tested and in need of upgrade

1. spotlight Due to: https://github.com/projectblacklight/spotlight/pull/3429

Testing in progress

1. blacklight_marc

Not yet tested

1. blacklight_oai_provider
2. blacklight_iiif_search
3. blacklight_advanced_search - release needed
4. geoblacklight - a number of UI issues, in progress PR open

---

Upgrade Notes

1. The shared/header_navbar partial no longer exists. If you used this in your application, then render blacklight_config.header_component.new(blacklight_config: blacklight_config) instead.

2. The catalog/constraints partial no longer exists. If you call this in your application, instead render blacklight_config.view_config(document_index_view_type).constraints_component.new(search_state: search_state)

3. If you use importmap-rails to access Blacklight Javascript files, change the line import 'blacklight' to import 'blacklight-frontend'. (probably in an application.js file)

4. If you used to use import 'blacklight-frontend/app/assets/javascripts/blacklight/blacklight', it should now be switched to import 'blacklight-frontend'

5. For SCSS, if you used to @import 'blacklight-frontend/app/assets/stylesheets/blacklight/blacklight';, it should now be switched to @import 'blacklight-frontend/stylesheets/blacklight';.

6. Blacklight::Document::Email and Blacklight::Document::Sms have been removed. You may need to modify your app/models/solr_document.rb to remove the use_extension for these.

7. Blacklight::ConstraintComponent now accepts a Blacklight::ClausePresenter, rather than a Blacklight::FacetItemPresenter

8. Blacklight::DocumentComponent's initializer no longer accepts a presenter parameter. Instead, pass a Blacklight::DocumentPresenter to the document parameter.

9. Blacklight::DocumentTitleComponent's initializer no longer accepts a document parameter. Instead, pass a Blacklight::DocumentPresenter to the presenter parameter.

10. Bootstrap 5 is now required. BL8 supported BS4 & BS5, but Bootstrap 4 reached EOL in Jan 2023. If you are upgrading from a Bootstrap 4 app, please consult Bootstrap's Migrating to v5 docs. Pay extra attention to all the changes there tagged as breaking (there are many).

11. Customizing CSS. Following Bootstrap's CSS evolution, a Blacklight 9 application's styles can be customized without requiring Sass compilation. Previous BL8 Sass variables like $logo-width have now been moved to native CSS custom properties (variables) like var(--bl-logo-width). See Blacklight's compiled blacklight.css file and Bootstrap's compiled bootstrap.css file to see available variables. Note that Bootstrap variables are prefixed with bs-* and Blacklight variables have bl-*.

12. Advanced Search. Blacklight's native/built-in advanced search (available at /catalog/advanced) is now enabled by default in BL9. If you were using it in BL8, you may have had to add some workarounds to get it to work correctly with different versions of Solr. You can likely remove those workarounds in BL9. Update your CatalogController with the advanced search changes made to BL9's catalog_controller.rb template used in the generator.

• To turn off advanced search, set config.advanced_search.enabled = false
• If you had created a separate Solr advanced requestHandler for BL8, you can likely remove it and use the default config.json_solr_path = 'select'
• In your facet field configuration, add include_in_advanced_search: false for any field that you don't want to appear in the advanced search form
• If you had added field.clause_params = { edismax: field.solr_parameters.dup } to any facet field config to support advanced search in BL8, you can now remove it; the correct clause_params will now be automatically set correctly.
• The default advanced search will display all facet fields, and all possible values for each (limit: -1). If any field has too many values for this to be practical, you might consider A) suppressing it with include_in_advanced_search: false; B) setting a specific limit using config.advanced_search.form_solr_parameters; C) adding a custom view and JS for multi-select facets.
• See #3742 for more details.