NOTE: This wiki provides developer documentation for the latest Blacklight release. For documentation of older releases, 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, and provides search box, facet constraints, stable document urls, etc., all of which is customizable via Rails (templating) mechanisms. Blacklight accommodates heterogeneous data, allowing different information displays for different types of objects.
Some other features include:
This wiki provides high-level documentation of Blacklight and supplements the low-level RubyDocs. It is structured to address a broad spectrum of needs, ranging from new developers getting started to well-experienced developers extending their application or troubleshooting. It should be of use at any point in the application life cycle.
This wiki assumes you have prior experience with Ruby and Ruby on Rails. If you have no prior experience with either, you will find a very steep learning curve diving straight into Blacklight. There are some good free resources on the internet for learning Ruby, including:
And resources for learning Rails, including:
In order to fully understand this guide, you should also familiarize yourself with Apache Solr, ways to index data into Solr, how to configure request handlers, and the Solr schema format. Those topics are covered in the official Apache Solr Tutorial.
Blacklight tries to address the "80% use case" out of the box and through some simple configuration can be adapted to work with your data. The available Blacklight configuration, and their default values, is shown in
The Blacklight configuration is an
OpenStruct; in addition to the Blacklight-defined configuration discussed in the sections below, you may also add application-specific configuration (e.g. for controlling behavior in overridden partials) or plugin-specific configuration.
There are many ways to override specific behaviors and views in Blacklight. Because Blacklight is distributed as a Rails engine-based gem, all customization of Blacklight behavior should be done within your application by overriding Blacklight-provided behaviors with your own.
Don't be scared to ask a question on the Blacklight mailing list. 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.
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.
Some Blacklight developers aso hang out on our IRC channel, usually during North American office hours. On
#blacklight. Stop in and say hi, we're happy to help with questions when we have time. http://freenode.net/faq.shtml.
This wiki provides developer documentation for the
master branch of Blacklight, which may include documentation of features not present in every Blacklight version. For documentation of specific Blacklight releases, see also:
Last edited by Chris Beer,