Major Changes

Supported Dependencies

Blacklight 6 requires Rails 4.1 (or greater). Among other features, Blacklight uses the Rails.application.secrets to generate temporary links for exported user content. Ruby on Rails provides helpful guides on how to migrate existing applications:

Blacklight also requires Ruby 2.0 or greater.

Blacklight also requires Solr 4, and Solr 5 is strongly recommended.

Routing changes

Blacklight now provides resourceful routing concerns that are mixed into an application's routes. The replaces the blacklight_for routing method. The intent is to create more explicit routing within the application in order to provide more visibility of Blacklight's routing expectations.

With the new routing, applications can create resourceful controllers to provide a Blacklight search experience:

# with a singular resource:
  resource :catalog, only: [:index] do
    concerns :searchable
  end

# or resources:
  resources :searchable_objects do
    collection do
      concerns :searchable
    end
  end

Two other routing changes are:

the blacklight engine provides routes for the search history and saved searches, and must be mounted within your application:

mount Blacklight::Engine => '/'

minor changes to named routes to better align with Rails resourceful routing. In particular, catalog_index_path is now search_catalog_path.

Blacklight::SearchBuilder

Blacklight provides a standard API for mapping user parameters to back-end query parameters. This replaces the controller-level .search_params_logic with a mapping class.

Instead of adding search_params_logic to your controller you will need to set up a default_processor_chain into your SearchBuilder. This means that instead of modifying your controller on the fly you can set up different SearchBuilders that encapsulate your search logic. This change should make it easier to test your search logic.

See the upgrade notes for how to convert your search_params_logic into SearchBuilder.

Blacklight::Path

Blacklight provides many URL helpers for generating search urls, and in Blacklight 6.x we've consolidated these methods in a Blacklight::Path class, which is made available to the controllers and helpers.

We've provided deprecation warnings, where appropriate, for the old helper methods, and will remove those helpers in Blacklight 7.

HTML markup and CSS changes

We've made minor changes to the Blacklight HTML markup to meet Web Content Accessibility Guidelines level AA. In particular, this meant:

re-aligning HTML header element, to ensure a consistent hierarchy in a page [https://github.com/projectblacklight/blacklight/commit/c4bf4871a38e8fcbf665e01344ff8a0f283ddff0]

We've also tried to clean up some of the provided CSS by creating smaller, more targeted SCSS files and remove styles that were not currently used by Blacklight [https://github.com//pull/1245]

Class and Module reorganization

We've moved many of the classes and modules in ./lib/blacklight into the ./app directory hierarchy in order to clarify the intended consumers for these model and controller mixins.

Remove deprecated code and views

Deprecated methods and templates have been marked as deprecated in Blacklight 5.x releases and have been removed in Blacklight 6.0.

Removed unused i18n keys [https://github.com/projectblacklight/blacklight/commit/e56214d8ad3d883172fe68a2d9313c36c02196b6]
Removed default Solr qt parameter [https://github.com//pull/1219]
Removed code that supported Ruby 1.9 and Rails 4.0
Remove code that supported Solr 1.4 and Solr 3.

Features

Add support for Rails 4 global ids for Blacklight::Document classes [https://github.com//pull/1222]
Add a simple search query autocomplete endpoint using twitter's typeahead library. [https://github.com//pull/1288]

Improvements

Improve facet wrapping and hyphenation to deal with long facet labels or counts. [https://github.com//pull/1263]
Add facet prefix filtering when paginating within a facet [https://github.com//pull/1262]
Use Rails' #to_sentence helper when rendering multivalued fields

Upgrade guide

Update your application to the latest Blacklight 5.x release (5.16.3, as of this writing) to receive notices of deprecated behaviors used in your local application.
Add explicit dependencies, as needed, to your application's Gemfile for:
```
  gem 'rsolr'

  # and
  gem 'blacklight-marc'
```

Update your routes to use the new resourceful routing scheme. Replace:

blacklight_for :catalog
# or
Blacklight.add_routes(self)

with explicit routing:

  mount Blacklight::Engine => '/'

  concern :searchable, Blacklight::Routes::Searchable.new
  concern :exportable, Blacklight::Routes::Exportable.new

  resource :catalog, only: [:index], controller: 'catalog' do
    concerns :searchable
  end

  resources :solr_documents, only: [:show], controller: 'catalog' do
    concerns :exportable
  end

  resources :bookmarks do
    concerns :exportable

    collection do
      delete 'clear'
    end
  end

Note that there are a handful of named routing changes from the Blacklight 5.x routes, including:

catalog_index_path is now search_catalog_path
catalog_facet_path is now facet_catalog_path
catalog_path is now solr_document_path
citation_catalog_path is now citation_solr_document_path

These changes help align Blacklight with Rails routing conventions.

If you haven't yet created the SearchBuilder, create a default search builder by running the generator
```
$ rails generate blacklight:search_builder
```

Replace search_params_logic in your Controllers with default_processor_chain in your SearchBuilder.

For any place in your Controllers where you call e.g. self.search_params_logic = [ <array of methods>] remove that from the controller and add it to app/models/search_builder.rb with line self.default_processor_chain += [<array of methods>].

For example if your CatalogController originally looks like this:

  class CatalogController < ApplicationController
     include Blacklight::Catalog

     self.search_params_logic += [:show_my_records]

     def show_my_records
        <do stuff to show my records>
     end

     ...
  end

Your catalog will then look like

  class CatalogController < ApplicationController
     include Blacklight::Catalog
     ...
  end

and your SearchBuilder will look like this

  class SearchBuilder < Blacklight::SearchBuilder
    include Blacklight::Solr::SearchBuilderBehavior

   self.default_processor_chain += [:show_my_records]

    def show_my_records
      <do stuff to show my records>
    end
  end

Contributors

Thanks, as always, to every contributor who helped with this release, including:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Blacklight 6.0.0.pre3