Home

NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, please see the end of this page.

Blacklight is an open source Ruby on Rails "engine" that provides a basic discovery interface for searching an Apache Solr index, including fielded searching, applying and removing facet constraints, sorting and paginating through search results, and more. As an engine, Blacklight components are customizable via Rails (templating) mechanisms to meet the search and discovery needs of heterogeneous data, allowing different information displays for different types of objects.

Other out-of-the-box features include:

Stable URLs for search and record pages allow users to bookmark, share, and save search queries for later access
A JSON API For searching and retrieving records
RSS and Atom feeds of search results
OpenURL/Z39.88 COinS support, allowing plugins like Zotero to easily extract data from the page.
OpenSearch and schema.org, a collection of simple formats for the sharing of search results.

About this guide

This wiki provides high-level documentation of Blacklight and supplements the inline code documentation (also available from RubyDocs). This wiki assumes you have prior experience with Ruby and Ruby on Rails. If you have no prior experience with either, there are some good free resources on the internet for learning Ruby, including:

And resources for learning Rails, including:

Additionally, you may want to review the official Apache Solr Tutorial, as the underlying search index and configuration provides and powers much of the Blacklight user experience but are outside the scope of this guide. This includes topics like how to index data into Solr, how to configure Solr request handlers, and the Solr schema format.

Requirements

Each version of Blacklight may have specific requirements for underlying technologies and inherits some requirements from upstream software (like Rails, Solr, etc). As of Blacklight 8, these requirements are:

Ruby 3.1 or greater
Rails 6.1 or greater (note that Rails has additional prerequisites, including SQLite3)
Solr 8 or greater (which again has its own system requirements, including Java 1.8 or greater)

In general, Blacklight provides support for currently supported version of Ruby, Ruby on Rails, and related components, and is known to work with versions of Solr all the way back to Solr 1.4 (although some Blacklight features and functionality may require more recent versions)

Getting started

The quickstart guide will walk you through running Solr, building a new Rails application with Blacklight, and indexing a sample set of records. You can also start from a pre-generated Blacklight application.

Additional workshop materials are available for learning how to customize and extend the application.

Features and configuration

Blacklight provides out-of-the-box support for many types of search interactions through configuration, and with additional customization can be adapted to work with many types of data and user experience needs.

Connecting to a Solr index
Indexing your data into Solr
Extending or Modifying Blacklight Search Behavior How to change the way the Blacklight discovery feature works.

Blacklight configuration

A list of available Blacklight configuration options, and their default values, is available at blacklight/configuration.rb. In addition to the Blacklight-defined configuration discussed here, you may also add application-specific configuration (e.g. for controlling behavior in overridden partials) or plugin-specific configuration.

General configuration

Fields

Customizing behavior

There are many ways to override Blacklight's out-of-the-box user experience and search interactions because Blacklight is distributed as a Rails engine that resides within your own application. This means that most any customization can be done within your application by overriding Blacklight-provided behaviors without needing Blacklight to support specific configuration for less common or application-specific use cases. That said, this wiki has a directory of Blacklight plugins that has some types of functionality that is not in core Blacklight but is easily shared across multiple applications.

Understanding Rails and Blacklight How the Blacklight engine integrates with your application

Providing your own view templates: Overriding the out-of-the-box Blacklight templates the Rails way.
Configuring Rails Routes

Customizing the UI

Theming: Overriding the Blacklight CSS
Pagination: Advice on how to customize pagination with Kaminari

Adding new document actions How to extend the document actions with application-specific behavior
Internationalization: Translating (or simply customizing) the Blacklight copy

Other Customizations

User Authentication: Connecting Blacklight with an existing Authentication system

Other Plugins

There are lots of plugins and add-ons, documented here.

API documentation

Support

Don't be scared to ask a question on the #blacklight channel in the Code4Lib Slack team. If you're not on Code4Lib Slack, you can request an invitation. This is the primary place where conversation takes place.

We appreciate you checking the documentation first and asking an educated question, but don't beat your head against the wall -- sometimes the existing documentation may be out of date and inaccurate.

There is also a Blacklight mailing list. In order to reduce spam, the first time you post your email will be held in a moderation queue, but as soon as your first message is approved your posts won’t be held for moderation any longer.

Contributing to Blacklight

Frequently asked Questions

FAQ

Older Documentation

This wiki provides developer documentation for the main branch of Blacklight, which may include documentation of features not present in every Blacklight version. For documentation of specific Blacklight releases, see also: