Upgrading to Blacklight 8

Upgrade Notes for Blacklight 7 to 8

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

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

Plugins tested against Blacklight 8

Tested and known to work

1. blacklight-hierarchy
2. blacklight_oai_provider

Tested and in need of upgrade

Not yet tested

---

NOTES

1. @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
2. Blacklight::SearchService#fetch now returns a single value rather than two values.
3. Remove component: true configuration from add_facet_field in CatalogController
4. 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.
5. 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
6. 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
7. app/views/catalog/_constraints_element.html.erb is no longer present. Overriding it has no effect.
8. Explicitly pass the documents to the render_document_index method:

• Deprecation warning: https://github.com/projectblacklight/blacklight/pull/2530/files

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

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. Sometimes called a kind of "breadcrumbs".
• Plugins often want to add elements to this "constraints" area.
  • They have traditionally done this by over-riding helper methods either render_constraints or render_constraints_filters to call super and concatenate their own additional content.
  • Multiple different plugins can and have done this simultaneously without stepping on each others toes, each adding something to super.
  • This will no longer work in Blacklight 8, those methods are not available for over-riding.
  • Additionally, when a plugin wants to supply it's own "constraint", it has often traditionaly called the render_constraint_element helper method, to say "render this constraint in whatever the application style is, even if it's been customized". That method is also no longer available.
• Examples:
  • blacklight_range_limit
  • geoblacklight
  • blacklight_maps
• Upgrade Path:
  • In BL 8 all the constraints are rendered by app/view/catalog/_constraints.html.erb That renders the following components:
  • Blacklight::ConstraintsComponent this used to be render_constraints
  • Blacklight::ConstraintLayoutComponent this used to be render_constraints_element
  • We could override the view partial to render a new subclass of Blacklight::ConstraintsComponent
  • Another possibility is to move the ConstraintsComponent class to a configuration variable and have the partial use that variable.

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.
• By over-riding the render_constraints_query helper method -- this is no longer available.
• Examples:
  • blacklight_advanced_search
• Upgrade Path:
  • In BL 8 the constraints query is rendered by the query_constraint_component argument (default Blacklight::ConstraintLayoutComponent), which is passed into the Blacklight::Constrains component: https://github.com/projectblacklight/blacklight/blob/fd33c74a378d164a571174fa0054c25b70ef09d1/app/components/blacklight/constraints_component.rb#L11 . To customize, provide a different 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.
• Previously, it could call the helper method render_constraints to render the constraints including any customizations added by plugins or local app, as above.
• This is no longer available as a method.
• Examples:
  • spotlight
• Upgrade Path: ??